HomeScreen

Since: BlackBerry 10.0.0

#include <bb/platform/HomeScreen>

To link against this class, add the following line to your .pro file: LIBS += -lbbplatform

The HomeScreen class encapsulates interactions between an application and the home screen on the device.

The HomeScreen class provides an API for interactions between an application and the home screen. The current set of possible interactions are:
  • Changing the wallpaper on the background of the home screen to a new image.

  • Notifications when the device becomes screen or password locked.

  • Adding shortcuts for URLs.

  • Notification when the device enters and exits bedside mode.

Note that, once created, objects of this class cannot have their thread affinity changed, either explicitly via QObject::moveToThread() or implicitly by changing the thread affinity of the parent of the object. Doing so results in undefined behavior.

Example usage:
#include <bb/platform/HomeScreen>

int main(int argc, char **argv) {
    bb::platform::HomeScreen homeScreen;
}


Overview

Public Functions Index

HomeScreen (QObject *parent=0)
virtual ~HomeScreen ()
Q_INVOKABLE booladdShortcut (const QUrl &iconPath, const QString &iconLabel, const QUrl &url)
boolisBedsideModeActive () const
Q_INVOKABLE bb::platform::DeviceLockState::TypelockState () const
Q_INVOKABLE boolsetWallpaper (const QUrl &wallpaperFile)
bb::platform::WallpaperLockState::TypewallpaperLockState () const

Signals Index

voidbedsideModeActiveChanged (bool newState)
voidlockStateChanged (bb::platform::DeviceLockState::Type newState)
voidwallpaperFinished (const QUrl &path, bb::platform::WallpaperResult::Type result)
voidwallpaperLockStateChanged (bb::platform::WallpaperLockState::Type wallpaperLockState)

Properties

bool bedsideModeActive[read-only]

Indicates whether the device is in bedside mode.

Since:

BlackBerry 10.0.0

bb::platform::DeviceLockState::Type lockState[read-only]

The lock state of the device.

See also:

bb::platform::DeviceLockState::Type for the list of lock states.

Accessing the lock state property in QML
// QML Plugin for libbbplatform
import bb.platform 1.0

import bb.cascades 1.0

Page {
    Container {

        // HomeScreen isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            HomeScreen {
                id: myHomeScreen
            }
        ]
        
        Button {
            text: "Print Lock State"
            
            onClicked: {
                // Of course, you can't press the button on a locked screen so you'll
                // never see either of the locked states.
                if (myHomeScreen.lockState == DeviceLockState.Unknown) {
                    console.log("No idea");
                } else if (myHomeScreen.lockState == DeviceLockState.Unlocked) {
                    console.log("Unlocked");
                } else if (myHomeScreen.lockState == DeviceLockState.ScreenLocked) {
                    console.log("Screen locked");
                } else if (myHomeScreen.lockState == DeviceLockState.PasswordLocked) {
                    console.log("Password locked");
                } else if (myHomeScreen.lockState == DeviceLockState.PinBlocked) {
                    console.log("PIN blocked");
                }
            }
        }
        
        // Additional QML
    }
}
Since:

BlackBerry 10.0.0

bb::platform::WallpaperLockState::Type wallpaperLockState[read-only]

Indicates the current wallpaper lock state.

See also:

bb::platform::WallpaperLockState::Type for the list of wallpaper lock states.

Since:

BlackBerry 10.2.0

Public Functions

HomeScreen (

Creates a new HomeScreen object.

Constructing a HomeScreen object in C++
#include <bb/platform/HomeScreen>

int main(int argc, char **argv) {
    bb::platform::HomeScreen homeScreen;
}
Constructing a HomeScreen object in QML
// QML Plugin for libbbplatform
import bb.platform 1.0

import bb.cascades 1.0

Page {
    Container {
    
        // HomeScreen isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            HomeScreen {
                id: myHomeScreen
            }
        ]

        // Additional QML, which can use myHomeScreen

    }
}
Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~HomeScreen ()

Destructor.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool addShortcut (

Add a URL-launching-shortcut to the home screen.

When the user clicks the shortcut, the URL is launched as if it were invoked via the InvokeManager.

The supplied icon path URL can be one of the following:
  • An asset associated with the application. The assets directory can be specified using the "asset:///" scheme in the URL. The path of the URL is interpreted as a relative path using the assets directory as the base. For example, QUrl("asset:///images/icon.png") uses an image from the assets directory.

  • An absolute path to the file. This can be specified using a "file:///" URL or simply supplying an absolute path with no scheme in the URL. For example, QUrl("file:///accounts/1000/shared/camera/icon.png") or QUrl("/accounts/1000/shared/camera/icon.png") uses the image file from the shared photos directory (assuming the application has permission to access shared files).

  • A relative path, relative to the root of the application's working directory. To provide a relative path, do not supply a scheme in the URL. Simply supply a relative path to the desired file. For example, QUrl("app/native/assets/images/icon.png") uses an image from the assets directory.

Unrecognized URL schemes will result in a failure.

The supplied icon path URL must refer to a file that contains a recognized image type. Recognized image files are those that end in one of the following extensions: .jpg, jpeg, .jfif, .jif, .jpe, or .png.

Note that if the size of the supplied icon is larger than the expected icon size, it will be scaled down to fit. However, the supplied icon will not be scaled up if it is smaller than the expected icon size. Consult the UI guidelines for the correct icon size for the device.

The supplied label is simplified before it is used. This process strips any leading and trailing whitespace, and any sequence of internal whitespace is replaced with a single space. Whitespace includes the characters '\t', '\n', '\v', '\f', '\r', and ' '.

Note that the supplied URL must be syntactically valid, but no effort is made to verify that any application is registered for the URL scheme or that the URL refers to a legitimate resource. If no URL handler exists for the provided scheme, then launching the shortcut will have no effect. A complete list of recognized URL schemes can be found in the documentation for the navigator_invoke() function.

Adding a shortcut in C++
#include <bb/platform/HomeScreen>
#include <QUrl>

int main(int argc, char **argv) {
    bb::platform::HomeScreen homeScreen;

    // Add a shortcut to RIM's home page to the Home Screen, with icon.png from the application's
    // assets and a label of "RIM Web Site".
    bool result = homeScreen.addShortcut(QUrl("asset:///icon.png"),
                                         "RIM Web Site",
                                         QUrl("http://www.rim.com"));
}
Adding a shortcut in QML
// QML Plugin for libbbplatform
import bb.platform 1.0

import bb.cascades 1.0

Page {
    Container {

        // HomeScreen isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            HomeScreen {
                id: myHomeScreen
            }
        ]
        
        Button {
            text: "Add shortcut"
            
            onClicked: {
                myHomeScreen.addShortcut("asset:///RIMicon.png,",
                                         "Research in Motion",
                                         "http://www.rim.com");
            }
        }
        
        // Additional QML
}
Parameters
iconPath

The path to the icon for the shortcut, to be shown on the device's home screen.

iconLabel

The label to appear under the icon on the device's home screen.

url

The URL to invoke when the shortcut is launched by the user.

Return:

true if the shortcut was successfully added to the home screen, false otherwise. Note that the shortcut is not added to the home screen if the icon path does not refer to a valid image file, the icon label is empty, or the URL is empty.

Since:

BlackBerry 10.0.0

bool isBedsideModeActive ()

Indicates whether the device is in bedside mode.

Return:

true if the device is in bedside mode, false otherwise.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::platform::DeviceLockState::Type lockState ()

Returns the current lock state of the device.

See also:

bb::platform::DeviceLockState for the list of device lock states.

Checking the lock state in C++
#include <bb/platform/HomeScreen>

void checkLockState()
{
    bb::platform::HomeScreen homeScreen;

    bb::platform::DeviceLockState::Type state = homeScreen.lockState();

    if (state == bb::platform::DeviceLockState::Unknown) {
        unknownLockState();
    } else if (state == bb::platform::DeviceLockState::Unlocked) {
        deviceUnlocked();
    } else if (state == bb::platform::DeviceLockState::ScreenLocked) {
        deviceScreenLocked();
    } else if (state == bb::platform::DeviceLockState::PasswordLocked) {
        devicePasswordLocked();
    } else if (state == bb::platform::DeviceLockState::PinBlocked) {
        devicePinBlocked();
    }
}
Checking the lock state in QML
// QML Plugin for libbbplatform
import bb.platform 1.0

import bb.cascades 1.0

Page {
    Container {

        // HomeScreen isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            HomeScreen {
                id: myHomeScreen
            }
        ]
        
        Button {
            text: "Print Lock State"
            
            onClicked: {
                // Of course, you can't press the button on a locked screen so you'll
                // never see either of the locked states.
                if (myHomeScreen.lockState == DeviceLockState.Unknown) {
                    console.log("No idea");
                } else if (myHomeScreen.lockState == DeviceLockState.Unlocked) {
                    console.log("Unlocked");
                } else if (myHomeScreen.lockState == DeviceLockState.ScreenLocked) {
                    console.log("Screen locked");
                } else if (myHomeScreen.lockState == DeviceLockState.PasswordLocked) {
                    console.log("Password locked");
                } else if (myHomeScreen.lockState == DeviceLockState.PinBlocked) {
                    console.log("PIN blocked");
                }
            }
        }
        
        // Additional QML
    }
}
Return:

The current lock state of the device.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool setWallpaper (
  • const QUrl &wallpaperFile)

Sets the home screen wallpaper for the current view to the supplied image.

The path is provided as a URL, but it must be a path on the file system. Legal path specifications are described below.

The image will be scaled to fit the screen.

If the wallpaper image is deleted while it is set as the current wallpaper (say, because the image is an asset in an application that is then deleted), the image will remain the wallpaper until the device is rebooted. At that point, the default wallpaper will be reapplied.

The new wallpaper is only applied to the currently active view (personal, work, etc.).

Note that this method now operates synchronously. The return value now indicates the results from the home screen, not that the request was successfully issued. A return value of true means the request was successfully processed, false indicates an error (which we interpret as the wallpaper being locked). There is no longer any need to use the wallpaperFinished() signal to get the results. However, for backwards compatibility, the signal is still emitted.

The supplied URL can be one of the following:
  • An asset associated with the application. The assets directory can be specified using the "asset:///" scheme in the URL. The path of the URL is interpreted as a relative path using the assets directory as the base. For example, QUrl("asset:///images/background.png") uses an image from the assets directory.

  • An absolute path to the file. This can be specified using a "file:///" URL or simply supplying an absolute path with no scheme in the URL. For example, QUrl("file:///accounts/1000/shared/camera/background.png") or QUrl("/accounts/1000/shared/camera/background.png") uses the image file from the shared photos directory (assuming the application has permission to access shared files).

  • A relative path, relative to the root of the application's working directory. To provide a relative path, do not supply a scheme in the URL. Simply supply a relative path to the desired file. For example, QUrl("app/native/assets/images/background.png") uses an image from the assets directory.

Unrecognized URL schemes will result in a failure.

The supplied URL must refer to a file that contains a recognized image type. Recognized image files are those that end in one of the following extensions: .jpg, jpeg, .jfif, .jif, .jpe, or .png.

Warning!

Note that this method does not validate the contents of the supplied image, just that the extension matches a recognized image file. As a result, the return value of this method only indicates if it successfully requested that the wallpaper be set to the supplied path, and not whether the wallpaper was successfully changed. If the path leads to an invalid image, this method may return true even though the wallpaper is not changed. Also note that supplying an invalid file will cause the wallpaper to be reset to the system default.

Setting the wallpaper in C++
#include <bb/platform/HomeScreen>
#include <QUrl>

void updateWallpaper()
{
    bb::platform::HomeScreen homeScreen;

    // Setting wallpaper to image bundled with an application's assets.
    bool result = homeScreen.setWallpaper(QUrl("asset:///bundledImage.png"));

    // Equivalent to the above, without the "asset:///" URL scheme.
    result = homeScreen.setWallpaper(QUrl("app/native/assets/bundledImage.png"));

    // If you application has access to shared files, you can use a camera picture
    // as the background.
    result = homeScreen.setWallpaper(QUrl("/accounts/1000/shared/camera/IMG_00000001.jpg"));

    // Alternate version of the previous example, using a "file:///" scheme.
    result = homeScreen.setWallpaper(QUrl("file:///accounts/1000/shared/camera/IMG_00000001.jpg"));
}
Setting the wallpaper in QML
// QML Plugin for libbbplatform
import bb.platform 1.0

import bb.cascades 1.0

Page {
    Container {

        // HomeScreen isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            HomeScreen {
                id: myHomeScreen
            }
        ]
        
        Button {
            text: "Change wallpaper"
            
            onClicked: {
                myHomeScreen.setWallpaper("asset:///newWallpaper.jpg");
            }
        }
        
        // Additional QML
}
Parameters
wallpaperFile

The URL to the file containing the new wallpaper image.

Return:

true if the wallpaper request was successfully processed by the home screen, false otherwise. This method may fail if there is a PPS failure, if the scheme in the URL is not recognized, if the supplied wallpaper file is invalid (does not exist, cannot be read, is a directory, or is not a recognized image file), or if the wallpaper is locked.

Since:

BlackBerry 10.0.0

bb::platform::WallpaperLockState::Type wallpaperLockState ()

Returns the current state of the wallpaper lock.

Return:

The state of the wallpaper lock. See bb::platform::WallpaperLockState for the list of possible states.

Since:

BlackBerry 10.2.0

Signals

void bedsideModeActiveChanged (
  • boolnewState)

Emitted when the device enters or leaves bedside mode.

Parameters
newState

true if the device is now in bedside mode, false otherwise.

Since:

BlackBerry 10.0.0

void lockStateChanged (

Emitted when the lock state on the device changes.

Note:

Due to a work around for a Qt Core issue with accessing enums from QML the argument of this signal doesn't follow naming convention for signals in which the signal arguments are typically named to match the associated property's name. Use the object's property to access current property value instead of the signal argument to avoid runtime errors (i.e., use lockState instead of newState).

Receiving the lock state changed signal in C++
#include <bb/Application>
#include <bb/platform/HomeScreen>
#include <bb/platform/WallpaperResult>

#include <QObject>
#include <QUrl>

class TestObject : public QObject
{
    Q_OBJECT

public Q_SLOTS:
    void onLockStateChanged(bb::platform::DeviceLockState::Type newState);
};

void onLockStateChanged(bb::platform::DeviceLockState::Type newState)
{
    if (newState == bb::platform::DeviceLockState::Unknown) {
        unknownLockState();
    } else if (newState == bb::platform::DeviceLockState::Unlocked) {
        deviceUnlocked();
    } else if (newState == bb::platform::DeviceLockState::ScreenLocked) {
        deviceScreenLocked();
    } else if (newState == bb::platform::DeviceLockState::PasswordLocked) {
        devicePasswordLocked();
    } else if (newState == bb::platform::DeviceLockState::PinBlocked) {
        devicePinBlocked();
    }
}

int main(int argc, char **argv)
{
    bb::Application app(argc, argv);
    bb::platform::HomeScreen homeScreen;
    TestObject testObject;

    QObject::connect(&homeScreen, SIGNAL( lockStateChanged(bb::platform::DeviceLockState::Type) ),
                     &testObject, SLOT( onLockStateChanged(bb::platform::DeviceLockState::Type) ));

    return app.exec();
}
Receiving the lock state changed signal in QML
// QML Plugin for libbbplatform
import bb.platform 1.0

import bb.cascades 1.0

Page {
    Container {

        // HomeScreen isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            HomeScreen {
                id: myHomeScreen
                
                onLockStateChanged: {
                    // Remember to use the property and not the parameter here.
                    console.log("Update " + lockState);
                    if (lockState == DeviceLockState.Unknown) {
                        console.log("No idea");
                    } else if (lockState == DeviceLockState.Unlocked) {
                        console.log("Unlocked");
                    } else if (lockState == DeviceLockState.ScreenLocked) {
                        console.log("Screen locked");
                    } else if (lockState == DeviceLockState.PasswordLocked) {
                        console.log("Password locked");
                    } else if (lockState == DeviceLockState.PinBlocked) {
                        console.log("PIN blocked");
                    }
                }
            }
        ]
        
        // Additional QML
    }
}
Parameters
newState

The new lock state of the device.

Since:

BlackBerry 10.0.0

void wallpaperFinished (

Emitted when a request to set the wallpaper is made, to provide the result of the request.

This result arrives in an event after the request is made.

Note that multiple requests to update the wallpaper using the same path cannot be differentiated. If you make several calls to set the wallpaper using the same path in rapid succession, you may find it difficult to associate a specific invocation of this signal with a specific request.

Receiving the wallpaper finished signal in C++
#include <bb/Application>
#include <bb/platform/HomeScreen>
#include <bb/platform/WallpaperResult>

#include <QDebug>
#include <QObject>
#include <QUrl>

class TestObject : public QObject
{
    Q_OBJECT

public Q_SLOTS:
    void onWallpaperFinished(const QUrl &path, bb::platform::WallpaperResult::Type result);
};

void onWallpaperFinished(const QUrl &path, bb::platform::WallpaperResult::Type result)
{
    if (result == bb::platform::WallpaperResult::Changed) {
        qWarning() << "Updated wallpaper to " << path.toUtf8().constData();
    } else if (result == bb::platform::WallpaperResult::Locked) {
        qWarning() << "Wallpaper locked - could not update to " << path.toUtf8().constData();
    }
}

int main(int argc, char **argv)
{
    bb::Application app(argc, argv);
    bb::platform::HomeScreen homeScreen;
    TestObject testObject;

    QObject::connect(&homeScreen, SIGNAL( wallpaperFinished(const QUrl &, bb::platform::WallpaperResult::Type) ),
                     &testObject, SLOT( onWallpaperFinished(const QUrl &, bb::platform::WallpaperResult::Type) ));

    homeScreen.setWallpaper("asset:///newWallpaper.png");

    return app.exec();
}
Receiving the wallpaper finished signal in QML
// QML Plugin for libbbplatform
import bb.platform 1.0

import bb.cascades 1.0

Page {
    Container {

        // HomeScreen isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            HomeScreen {
                id: myHomeScreen
                
                onWallpaperFinished: {
                    if (result == WallpaperResult.Changed) {
                        console.log("Wallpaper updated with " + path);
                    } else if (result == WallpaperResult.Locked) {
                        console.log("Wallpaper locked - not changed to " + path);
                    }
                }
            }
        ]
        
        Button {
            text: "Change wallpaper"
            
            onClicked: {
                myHomeScreen.setWallpaper("asset:///newWallpaper.jpg");
            }
        }
        
        // Additional QML
}
Parameters
path

The path that was supplied to the setWallpaper() method.

result

The result of the request to set the wallpaper. See bb::platform::WallpaperResult for the list of possible results.

Since:

BlackBerry 10.0.0

void wallpaperLockStateChanged (

Emitted when the wallpaper lock state on the device changes.

Parameters
wallpaperLockState

The new wallpaper lock state of the device.

Since:

BlackBerry 10.2.0

Last modified: 2014-06-24



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

comments powered by Disqus