Application

Since: BlackBerry 10.0.0

#include <bb/Application>

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

The Application class is used as the basis for your own custom application.

This class provides a simple set of wrappers for the lifecycle events that you will need during the execution of your application.

This class is used by non-Cascades applications, or applications providing their own UI framework functionality. If you are creating a GUI application, you should use the bb::cascades::Application class.

Only one instance of the Application class should be used in your application.

Example usage in C++
#include <bb/Application>

int main(int argc, char **argv) {
    bb::Application app(argc, argv);

    return app.exec();
}


Overview

Inheritance

Public Types Index

Only has inherited public types

enum Encoding

CodecForTr, UnicodeUTF8, DefaultCodec CodecForTr

bool(*EventFilter

Public Functions Index

Application (int &argc, char **argv)
virtual ~Application ()
Q_INVOKABLE boolclearClosePrompt ()
voidderegisterWindowGroup (const QString &windowGroupID)
Q_INVOKABLE boolisAsleep () const
Q_INVOKABLE boolisAwake () const
Q_INVOKABLE boolisFullscreen () const
Q_INVOKABLE boolisInvisible () const
Q_INVOKABLE boolisThumbnailed () const
Q_INVOKABLE boolisWindowGroupAsleep (const QString &windowGroupID) const
Q_INVOKABLE boolisWindowGroupAwake (const QString &windowGroupID) const
Q_INVOKABLE boolisWindowGroupFullscreen (const QString &windowGroupID) const
Q_INVOKABLE boolisWindowGroupInvisible (const QString &windowGroupID) const
Q_INVOKABLE boolisWindowGroupThumbnailed (const QString &windowGroupID) const
Q_INVOKABLE boolsetClosePrompt (const QString &title, const QString &message)
voidsetMainWindowGroup (const QString &mainWindowGroupID)
boolfilterEvent (void *message, long *result)Inherited
virtual boolnotify (QObject *, QEvent *)Inherited
QCoreApplication (int &argc, char **argv, int=ApplicationFlags)Inherited
EventFiltersetEventFilter (EventFilter filter)Inherited

Static Public Functions Index

bb::Application *instance ()
voidaddLibraryPath (const QString &)Inherited
QStringapplicationDirPath ()Inherited
QStringapplicationFilePath ()Inherited
QStringapplicationName ()Inherited
qint64applicationPid ()Inherited
QStringapplicationVersion ()Inherited
QStringListarguments ()Inherited
boolclosingDown ()Inherited
intexec ()Inherited
voidexit (int retcode=0)Inherited
voidflush ()Inherited
boolhasPendingEvents ()Inherited
voidinstallTranslator (QTranslator *messageFile)Inherited
QStringListlibraryPaths ()Inherited
QStringorganizationDomain ()Inherited
QStringorganizationName ()Inherited
voidpostEvent (QObject *receiver, QEvent *event)Inherited
voidpostEvent (QObject *receiver, QEvent *event, int priority)Inherited
voidprocessEvents (QEventLoop::ProcessEventsFlags flags=QEventLoop::AllEvents)Inherited
voidprocessEvents (QEventLoop::ProcessEventsFlags flags, int maxtime)Inherited
voidremoveLibraryPath (const QString &)Inherited
voidremovePostedEvents (QObject *receiver)Inherited
voidremovePostedEvents (QObject *receiver, int eventType)Inherited
voidremoveTranslator (QTranslator *messageFile)Inherited
boolsendEvent (QObject *receiver, QEvent *event)Inherited
voidsendPostedEvents (QObject *receiver, int event_type)Inherited
voidsendPostedEvents ()Inherited
voidsetApplicationName (const QString &application)Inherited
voidsetApplicationVersion (const QString &version)Inherited
voidsetAttribute (Qt::ApplicationAttribute attribute, bool on=true)Inherited
voidsetLibraryPaths (const QStringList &)Inherited
voidsetOrganizationDomain (const QString &orgDomain)Inherited
voidsetOrganizationName (const QString &orgName)Inherited
boolstartingUp ()Inherited
booltestAttribute (Qt::ApplicationAttribute attribute)Inherited
QStringtranslate (const char *context, const char *key, const char *disambiguation=0, Encoding encoding=CodecForTr)Inherited
QStringtranslate (const char *context, const char *key, const char *disambiguation, Encoding encoding, int n)Inherited

Protected Functions Index

Only has inherited protected functions

virtual boolcompressEvent (QEvent *, QObject *receiver, QPostEventList *)Inherited
virtual boolevent (QEvent *)Inherited
QCoreApplication (QCoreApplicationPrivate &p)Inherited

Public Slots Index

boolautoExit () const
boolextendTerminationTimeout ()
boolminimize ()
voidpoolingComplete (const QString &poolRequestID) const
boolrequestExit ()
voidsetAutoExit (bool autoExit)
boolsetIconBadge (bb::IconBadge::Type badge)
voidquit ()Inherited

Signals Index

voidasleep ()
voidautoExitChanged (bool newAutoExit)
voidawake ()
voidfullscreen ()
voidinvisible ()
voidmanualExit ()
voidpooling (const QString &poolRequestID)
voidprocessStateChanged (bb::ProcessState::Type processState)
voidswipeDown ()
voidthumbnail ()
voidwindowGroupAsleep (const QString &windowGroupID)
voidwindowGroupAwake (const QString &windowGroupID)
voidwindowGroupFullscreen (const QString &windowGroupID)
voidwindowGroupInvisible (const QString &windowGroupID)
voidwindowGroupThumbnailed (const QString &windowGroupID)
voidaboutToQuit ()Inherited
voidunixSignal (int)Inherited

Public Types

(Only has inherited public types)

Encoding Inherited

CodecForTr
UnicodeUTF8
DefaultCodec CodecForTr

typedef bool(* EventFilter Inherited

Properties

bool autoExit

The auto exit flag, for controlling the behavior of an exiting application.

Since:

BlackBerry 10.0.0

QString applicationNameInherited

QString applicationVersionInherited

QString organizationDomainInherited

QString organizationNameInherited

Public Functions

Application (
  • int &argc,
  • char **argv )

Initializes a new instance of the Application class.

Normal usage of the constructor expects the argc and argv from main() to be passed in. These values will be made available through the QCoreApplication::arguments() method.

Constructing an Application object in C++
#include <bb/Application>

int main(int argc, char **argv) {
    bb::Application app(argc, argv);

    return app.exec();
}
It is not possible to create an instance of this class in QML. Instead, an instance of this class must be created in C++ and exported to QML with the QmlDocument::setContextProperty() method. For Cascades applications, the bb::cascades::Application object returned by the method bb::cascades::Application::instance() is automatically exported to QML as a context property using the property name Application. Since bb::cascades::Application is a subclass of this class, all methods, signals, and slots can be used via this property. All QML examples in this documentation will assume the presence of a property named Application that provides access to an instance of bb::cascades::Application that represents this application.
Warning!

The data referred to by argc and argv must stay valid for the entire lifetime of the Application object. In addition, argc must be greater than zero and argv must contain at least one valid character string.

Parameters
argc

The number of entries in the argument array argv passed to the Application instance

argv

The array of parameters to the Application.

Since:

BlackBerry 10.0.0

virtual~Application ()

Destructor.

When the Application is destroyed, all signals and slots are disconnected.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool clearClosePrompt ()

Clears the current close prompt.

This function removes any close prompt that was set, regardless of which ApplicationSupport or Application object set the prompt. When the close prompt is cleared, no close prompt dialog box will appear when the user tries to close the application, and the application exits normally.

If there is no current close prompt, this method has no effect.

Example usage in C++
#include <bb/Application>

void saveApplicationData(bb::Application &myApp)
{
    saveData();

    // Application can now close cleanly since data is saved.
    myApp.clearClosePrompt();
}
Example usage in QML
import bb.cascades 1.0

Page {
    Container {
        
        Button {
            text: "Save"
            
            onClicked: {
                saveData();
                Application.clearClosePrompt();
            }
        }
        
        // Additional QML
    }
}
Return:

true if the close prompt was cleared, false otherwise.

Since:

BlackBerry 10.0.0

void deregisterWindowGroup (

Deregisters the provided window group.

After deregistering, all state information about the window group is discarded.

Note that you do not have to explicitly register a window group for state to be maintained. This class automatically maintains the window state about any window group for which state events are received. When deleting a window group, it can be beneficial to deregister it so that state information is no longer maintained in memory.

Parameters
windowGroupID

The ID of the window group to deregister. If the window group is not recognized, this method does nothing.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool isAsleep ()

Indicates if the main window group for the application is currently inactive.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state.

Return:

true if the main window group for the application is currently inactive, false otherwise.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isAwake ()

Indicates if the main window group for the application is currently active.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state.

Return:

true if the main window group for the application is currently active, false otherwise.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isFullscreen ()

Indicates if the main window group for the application is currently fullscreen.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state.

Return:

true if the main window group for the application is currently fullscreen, false otherwise.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isInvisible ()

Indicates if the main window group for the application is currently invisible.

A window group is invisible if it cannot be seen on the display.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state.

Return:

true if the main window group for the application is currently invisible, false otherwise.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isThumbnailed ()

Indicates if the main window group for the application application is currently thumbnailed.

A window group is thumbnailed if is is currently not fullscreen but is still visible on the display.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state.

Return:

true if the main window group for the application is currently thumbnailed, false otherwise.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isWindowGroupAsleep (

Indicates if the given window group is currently inactive.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state. Specifically, the process must receive an execution state update from Navigator with the given windowGroupID before this method can return a correct result.

Parameters
windowGroupID

The ID of the window group that is being queried.

Return:

true if the supplied window group is currently inactive, false otherwise. If the window group is not recognized, this method returns false.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isWindowGroupAwake (

Indicates if the given window group is currently active.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state. Specifically, the process must receive an execution state update from Navigator with the given windowGroupID before this method can return a correct result.

Parameters
windowGroupID

The ID of the window group that is being queried.

Return:

true if the supplied window group is currently active, false otherwise. If the window group ID is not recognized, this method returns false.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isWindowGroupFullscreen (

Indicates if the given window group is currently fullscreen.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state. Specifically, the process must receive a UI state update from Navigator with the given windowGroupID before this method can return a correct result.

Parameters
windowGroupID

The ID of the window group that is being queried.

Return:

true if the supplied window group is currently fullscreen, false otherwise. If the window group is not recognized, this method return false.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isWindowGroupInvisible (

Indicates if the given window group is currently invisible.

A window group is invisible if it cannot be seen on the display.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state. Specifically, the process must receive a UI state update from Navigator with the given windowGroupID before this method can return a correct result.

Parameters
windowGroupID

The ID of the window group that is being queried.

Return:

true if the supplied window group is currently invisible, false otherwise. If the window group is not recognized, this method returns false.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool isWindowGroupThumbnailed (

Indicates if the given window group is currently thumbnailed.

A window group is thumbnailed if is is currently not fullscreen but is still visible on the display.

If this method is called before Navigator events are processed, this method will return false since the application has not updated its state. Specifically, the process must receive a UI state update from Navigator with the given windowGroupID before this method can return a correct result.

Parameters
windowGroupID

The ID of the window group that is being queried.

Return:

true if the supplied window group is currently thumbnailed, false otherwise. If the window group is not recognized, this method returns false.

Since:

BlackBerry 10.2.0

Q_INVOKABLE bool setClosePrompt (

Sets a prompt to appear when the user attempts to close the application.

This function allows an application to prevent the user from closing the application without warning. If the user tries to close the application, a dialog box is displayed with the title and message specified. The dialog box will have 2 buttons: "Cancel" and "Close". If the user selects "Close", the application will be closed. If the user selects "Cancel", the dialog box will close and the application will continue running.

Note that the save prompt for an application is stored persistently on the device. The last call to this method on any ApplicationSupport or Application object determines the close prompt that will be shown. The close prompt persists until clearClosePrompt() is called on any ApplicationSupport or Application object. Destroying the object that set the close prompt does not reset the value.

Note that all commas and double quotes are stripped from the title and message parameters before they are displayed. These characters cannot be displayed correctly. If the text also includes backslash characters ('\'), this process can introduce unexpected white space characters like tabs ('\t') and newlines ('\n'). Since these whitespace characters are allowed in the dialog box, they cannot be stripped.

Escape characters can be used, but they may be awkward to specify. The string provided to this method is in turn forwarded to the device's home screen process, which interprets the string a second time, including any escape characters. This can require multiple levels of escaping to produce the desired effect. For instance, to add a backslash ('\') character to the close prompt, the string "\\\\" must be used. This provides the string "\\" to this object. When this string is forwarded to the home screen, "\\" is interpreted again to become '\'.

Setting a close prompt in C++
#include <bb/Application>

void applicationDataChanged(bb::Application &myApp)
{
    // Warn the user if they try to quit without saving.
    myApp.setClosePrompt("Unsaved changes", "The application has unsaved changes.");
}
Setting a close prompt in QML
import bb.cascades 1.0

Page {
    Container {
        TextField {
            onTextChanging: {
                Application.setClosePrompt("Unsaved changes",
                                           "The application has unsaved changes.");
            }
            // Other properties
        }
        // Additional QML
    }
}
Parameters
title

The title of the close prompt dialog box. This title replaces the current close prompt title if it is already set.

message

The message of the close prompt dialog box. This message replaces the current close prompt message if it is already set.

Return:

true if the close prompt was set, false otherwise.

Since:

BlackBerry 10.0.0

void setMainWindowGroup (

Sets the main window group ID for this application.

This method can be used to register a specific window group as the application's main window group. The signals thumbnail(), fullscreen(), invisible(), asleep(), and awake() will be emitted when the corresponding event occurs on either no window group (window group ID of "none") or on the application's main window group.

If this method is not called, then the application's main window group will be the first valid window group that appears in a lifecycle event. A valid window group ID is a non-empty string that is not the value "none". For applications that do not use window groups or use a single window group (the default in a Cascades application), this default behavior should produce correct results for the five lifecycle signals (thumbnail(), fullscreen(), invisible(), asleep(), and awake()).

If an application creates multiple window groups (which must be done explicitly), then this method can be called to ensure the application's main group is set correctly. In this case, you should consider using the five lifecycle events augmented with the window group ID to receive more precise lifecycle information. These augmented signals are windowGroupThumbnailed(const QString &), windowGroupFullscreen(const QString &), windowGroupInvisible(const QString &), windowGroupAsleep(const QString &), and windowGroupAwake(const QString &).

Parameters
mainWindowGroupID

The ID of the application's main window group. If this ID is empty or holds the value "none" then the main window group ID is not updated.

Since:

BlackBerry 10.0.0

bool filterEvent (
  • void *message,
  • long *result )
Inherited

virtual bool notify (Inherited

QCoreApplication (
  • int &argc,
  • char **argv,
  • int )
Inherited

EventFilter setEventFilter (
  • EventFilterfilter)
Inherited

Static Public Functions

bb::Application * instance ()

Returns a pointer to the application's bb::Application instance.

If no instance has been allocated, or if the application instance is not a bb::Application, null is returned.

Return:

A pointer to the bb::Application instance or 0 if Application has not been instantiated (or is not a bb::Application).

Since:

BlackBerry 10.0.0

void addLibraryPath (Inherited

QString applicationDirPath ()Inherited

QString applicationFilePath ()Inherited

QString applicationName ()Inherited

qint64 applicationPid ()Inherited

QString applicationVersion ()Inherited

QStringList arguments ()Inherited

bool closingDown ()Inherited

int exec ()Inherited

void exit (
  • intretcode)
Inherited

void flush ()Inherited

bool hasPendingEvents ()Inherited

void installTranslator (Inherited

QStringList libraryPaths ()Inherited

QString organizationDomain ()Inherited

QString organizationName ()Inherited

void postEvent (Inherited

void postEvent (Inherited

void processEvents (
  • QEventLoop::ProcessEventsFlagsflags)
Inherited

void processEvents (
  • QEventLoop::ProcessEventsFlagsflags,
  • intmaxtime )
Inherited

void removeLibraryPath (Inherited

void removePostedEvents (Inherited

void removePostedEvents (Inherited

void removeTranslator (Inherited

bool sendEvent (Inherited

void sendPostedEvents (Inherited

void sendPostedEvents ()Inherited

void setApplicationName (Inherited

void setApplicationVersion (Inherited

void setAttribute (
  • Qt::ApplicationAttributeattribute,
  • boolon )
Inherited

void setLibraryPaths (Inherited

void setOrganizationDomain (Inherited

void setOrganizationName (Inherited

bool startingUp ()Inherited

bool testAttribute (
  • Qt::ApplicationAttributeattribute)
Inherited

QString translate (
  • const char *context,
  • const char *key,
  • const char *disambiguation,
  • Encodingencoding )
Inherited

QString translate (
  • const char *context,
  • const char *key,
  • const char *disambiguation,
  • Encodingencoding,
  • intn )
Inherited

Protected Functions

(Only has inherited protected functions)

virtual bool compressEvent (Inherited

virtual bool event (Inherited

QCoreApplication (
  • QCoreApplicationPrivate &p)
Inherited

Public Slots

bool autoExit ()

Returns the value of the auto exit flag.

The flag is set using the setAutoExit(bool) method.

Obtaining the value of the auto exit flag in C++
#include <bb/Application>

void checkAutoExitState(bb::Application &myApp)
{
    if ( app.autoExit() ) {
        autoExitEnabled();
    } else {
        autoExitDisabled();
    }
}
Obtaining the value of the auto exit flag in QML
import bb.cascades 1.0

Page {
    Container {
        
        Button {
            text: "Print Auto Exit Value"
            
            onClicked: {
                 if (Application.autoExit) {
                     console.log("Auto exit enabled");
                 } else {
                     console.log("Auto exit disabled");
                 }
            }
        }
        
        // Additional QML
    }
}
Return:

The value of the auto exit flag.

Since:

BlackBerry 10.0.0

bool extendTerminationTimeout ()

Gives the application two more seconds to exit before being automatically killed.

An exiting application has three seconds to complete any shutdown and exit. After three seconds, the application will be automatically killed. If the application needs more than three seconds, this method can extend the termination timeout.

After calling this method, the application has two seconds to terminate before it is automatically killed. Note that this does not add two seconds to the existing timeout, but rather resets the timeout to two seconds from the time this method is called. So if an application calls this method immediately after being told to exit, the application has only two seconds (down from the original timeout of three seconds) to exit.

This method can be called multiple times to extend the termination timeout for longer periods of time.

Extending the termination timeout in C++
#include <bb/Application>

void applicationExiting(bb::Application &myApp)
{
    // Takes 2.5 seconds.
    cleanupPart1();

    myApp.extendTerminationTimeout();

    // Takes 1.5 seconds.  Parts 1 and 2 together would take
    // too long to complete without extending the timeout.
    cleanupPart2();
}
Extending the termination timeout in QML
import bb.cascades 1.0

Page {
    Container {
        TestObject {
            onExit: {
                // Takes 2.5 seconds.
                cleanupPart1();

                Application.extendTerminationTimeout();

                // Takes 1.5 seconds.  Parts 1 and 2 together would take
                // too long to complete without extending the timeout.
                cleanupPart2();
            }
        }
        // Other QML code
    }
}
Return:

true if the request to extend the timeout was successful, false otherwise.

Since:

BlackBerry 10.0.0

bool minimize ()

Minimizes the application window to a thumbnail and sends the user to the application switcher on the home screen.

This method causes the application to minimize itself into a thumbnail. This operation is identical to the user swiping up from the bottom touch-sensitive bezel into the screen. The user is taken to the application switcher on the device's home screen.

Example usage in C++
#include <bb/Application>
#include <QDebug>

void programmiticThumbnail(bb::Application &myApp) {
    bool success = myApp.minimize();
    if (!success) {
        qWarning() << "Minimize failed";
    }
}
Example usage in QML
import bb.cascades 1.0

Page {
    Container {
        
        Button {
            text: "Programmatic Thumbnail"
            onClicked: {
                Application.minimize();
            }
        }

        // Additional QML
    }
}
Return:

true if the minimize request was successfully sent, false otherwise.

Since:

BlackBerry 10.0.0

void poolingComplete (

Call this method when the application has finished setting its restoration state and wishes to be pooled.

This method should be called after setting the application's restoration state in a slot attached to the pooling() signal. The request identifier parameter in this method is the identifier from the signal argument.

If this method is not called within one second of receiving the pooling() signal, the application will be terminated rather than pooled.

Parameters
poolRequestID

The identifier for the pooling request, supplied by the pooling(const QString &) signal.

Since:

BlackBerry 10.0.0

bool requestExit ()

Requests that Navigator close the application.

An application should call this method if it decides that it needs to exit. This method informs Navigator that the application wishes to exit. In response, Navigator posts an exit event to the application. The application should wait for this event then shut down normally.

Note:

In general, applications should not programmatically exit. They should terminate only when explicitly closed by the end user.

Example usage in C++
#include <bb/Application>

void quitApplication(bb::Application &myApp)
{
    myApp.requestExit();
}
Example usage in QML
import bb.cascades 1.0

Page {
    Container {
        
        Button {
            text: "Quit"
            
            onClicked: {
                Application.requestExit();
            }
        }
        
        // Additional QML
    }
Return:

true if the close request was successfully sent, false otherwise.

Since:

BlackBerry 10.0.0

void setAutoExit (
  • boolautoExit)

Sets the behavior for an exiting application.

The value of the auto exit flag dictates the behavior of an exiting application.

If the auto exit flag is true, then this application will automatically call quit() on this object to exit the application's event loop when the application is closed by the user. This will result in the QCoreApplication::aboutToQuit() signal being emitted, which can be used for any necessary clean up. Note that this cleanup code must complete within three seconds or the application will be automatically killed. Also note that the manualExit() signal will not be emitted.

If the auto exit flag is false, then the application assumes responsibility for the process of exiting the application. The manualExit() signal is emitted, so the application can perform any necessary actions. The application has three seconds to complete the exit process or be killed, if in release mode. If more time is needed, the application can request additional time by calling the extendTerminationTimeout() method. When all actions are complete, the application must call quit() on this object.

Note that if quit() isn't called within the three second timeframe, and the app is being run in debug mode, the app will NOT be slain by the operating system to allow for more indepth debugging. If the app is running in release mode, it will be slain.

To avoid potential races with respect to exiting an application, make sure that a slot is connected to the manualExit() signal before the auto exit flag is set to false.

Note that this method has no effect after the manualExit() or QCoreApplication::aboutToQuit() signal has been emitted.

By default, the auto exit flag is set to true, so the application will exit automatically.

Setting the auto exit flag in C++
#include <bb/Application>

int main(int argc, char **argv) {
    bb::Application app(argc, argv);

    app.setAutoExit(false);

    // Make sure to connect a to the manualExit() signal to handle exit.

    return app.exec();
}
Setting the auto exit flag in QML
import bb.cascades 1.0

Page {
    Container {       
        Button {
            text: "Disable Auto Exit"
            
            onClicked: {
                // This is a property in QML.
                Application.autoExit = false;
            }
        }
        
        // Additional QML
    }
}
Parameters
autoExit

The new value of the auto exit flag.

Since:

BlackBerry 10.0.0

bool setIconBadge (

Applies a badge to the application's icon on the home screen and the window frame when the application is thumbnailed.

Once applied, the badge will still be applied to the application's icon after the application exits. However, a badge will not persist across device resets.

Setting the icon badge of an application in C++
#include <bb/Application>

void applicationHasInformation(bb::Application &myApp)
{
    myApp.setIconBadge(bb::IconBadge::Splat);
}

void acknowledgeInformation(bb::Application &myApp)
{
    myApp.setIconBadge(bb::IconBadge::None);
}
Setting the icon badge of an application in QML
import bb.cascades 1.0

Page {
    Container {
        
        Button {
            text: "Splat Badge"
            onClicked: {
                Application.setIconBadge(IconBadge.Splat);
            }
        }

        Button {
            text: "Remove Badge"
            onClicked: {
                Application.setIconBadge(IconBadge.None);
            }
        }
        
        // Additional QML
    }
}
Parameters
badge

The new badge to be applied.

Return:

true if the badge was successfully applied, false otherwise.

Since:

BlackBerry 10.0.0

void quit ()Inherited

Signals

void asleep ()

Emitted when the application becomes inactive.

Any slot attached to this signal is notified when the application becomes inactive. This occurs when the application is no longer in the foreground and the device decides that your application should no longer execute.

When this signal is received the Application should attempt to reduce CPU usage as much as possible, such as by presenting a "pause" or other suitable mechanism.

The state of the application's main window group is considered to be the state of the Application as a whole.

Note:

If you connect to both this signal and windowGroupAsleep(const QString &) then you will receive duplicate notifications for the application's main window group.

Example usage in C++
void TestObject::onAsleep() {
    // Do something here
}

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

    QObject::connect(&app, SIGNAL( asleep() ), &testObject, SLOT( onAsleep() ));
See full example
Example usage in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.asleep.connect(onAsleep);
    }
    
    function onAsleep() {
        applicationAsleep();
    }
    // Other QML
}
Since:

BlackBerry 10.0.0

void autoExitChanged (
  • boolnewAutoExit)

Emitted when the auto exit flag changes.

Example usage in C++
void TestObject::onAutoExitChanged(bool newAutoExitValue) {
    // Handle event here.
}

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

    QObject::connect(&app, SIGNAL( autoExitChanged(bool) ), &testObject, SLOT( onAutoExitChanged(bool) ));
See full example
Example usage in QML
import bb.cascades 1.0

Page {
    Container {
        Label {
            // The autoExitChanged signal permits property binding.
            text: "Auto exit value " + Application.autoExit
        }
    // Other QML
    }
}
Parameters
newAutoExit

The new value of the auto exit flag.

Since:

BlackBerry 10.0.0

void awake ()

Emitted when the application becomes active.

Any slot attached to this signal is notified when your application becomes active. This occurs when the application transitions to the foreground.

When this signal is received the Application should resume all normal activity.

The state of the application's main window group is considered to be the state of the Application as a whole.

Note:

If you connect to both this signal and windowGroupAwake(const QString &) then you will receive duplicate notifications for the application's main window group.

Example usage in C++
void TestObject::onAwake() {
    // Do something here
}

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

    QObject::connect(&app, SIGNAL( awake() ), &testObject, SLOT( onAwake() ));
See full example
Example usage in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.awake.connect(onAwakened);
    }
    
    function onAwakened() {
        applicationAwakened();
    }
    // Other QML
}
Since:

BlackBerry 10.0.0

void fullscreen ()

Emitted when the application is restored to fullscreen status.

This signal is emitted when the application is restored to fullscreen, such as after being thumbnailed, or if it becomes the active application from the task switcher interface.

The state of the application's main window group is considered to be the state of the Application as a whole.

Note:

If you connect to both this signal and windowGroupFullscreen(const QString &) then you will receive duplicate notifications for the application's main window group.

Example usage in C++
void TestObject::onFullscreen() {
    // Do something here
}

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

    QObject::connect(&app, SIGNAL( fullscreen() ), &testObject, SLOT( onFullscreen() ));
See full example
Example use in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.fullscreen.connect(onFullscreen);
    }
    
    function onFullscreen() {
        applicationFullscreen();
    }
    // Other QML
}
Since:

BlackBerry 10.0.0

void invisible ()

Emitted when the application is no longer visible.

Any slot attached to this signal is notified when your application is no longer visible. Your application is considered to be no longer visible when your application window is outside the viewable area of the Navigator. This includes when your window is off-screen during a task switch, or when the tray is raised and obscures all application windows, etc.

The state of the application's main window group is considered to be the state of the Application as a whole.

Note:

If you connect to both this signal and windowGroupInvisible(const QString &) then you will receive duplicate notifications for the application's main window group.

Example usage in C++
void TestObject::onInvisible() {
    // Do something here
}

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

    QObject::connect(&app, SIGNAL( invisible() ), &testObject, SLOT( onInvisible() ));
See full example
Example usage in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.invisible.connect(onInvisible);
    }
    
    function onInvisible() {
        applicationInvisible();
    }
    // Other QML
}
Since:

BlackBerry 10.0.0

void manualExit ()

Emitted when the application is closed by the user or by the system with the auto exit flag set to false.

If the application is handling the exit process, then this signal is emitted when the application is closed. Any code that needs to be run to shut down the application should be placed in a slot connected to this signal. The slot is also responsible for calling the quit() method on this object to slow down the application's event loop, and ensure that it has sufficient time to complete any actions.

This signal is not emitted if the application is killed because the application is considered to be unresponsive.

This signal is not emitted if the auto exit flag is set to true.

See also:

setAutoExit(bool) for more details on handling application exit.

Example usage in C++ See full example
Example usage in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.manualExit.connect(onManualExit);
    }
    
    function onManualExit() {
        // This must exit the application.
        exitApplication();
    }
    // Other QML that must set Application.autoExit = false for the above signal
    // to be emitted.
}
Since:

BlackBerry 10.0.0

void pooling (

Emitted when the application is being asked to be put in to the application pool.

This signal is received when the user closes the application. The application can choose to be pooled in memory rather than terminated. A pooled process is still running but has no visible windows. Restoring a pooled application is faster than launching a new instance.

This signal allows an application to set its restoration state, which is the state from which the application will resume when it is restored from the pool. Typically, the application will reset its UI state so restoring the pooled application will appear identical to a fresh launch. However, the application can choose other restoration states if it wishes to resume from some other state. The restoration state should be determined when the application is pooled rather than when it is next restored, as changing the UI on restoration can result in flickers as the UI updates or can result in stale data appearing in the UI.

The application must call the poolingComplete() method with the pool request identifier within one second of receiving this signal to indicate that the application has set its restoration state and wishes to be pooled. Otherwise, the application will be terminated rather than pooled.

After being pooled, the application should enter the bb::ProcessState::Stopped state, and become invisible and inactive. Restoring the application from the pool is similar to restoring the application from a thumbnail. It should enter the bb::ProcessState::Foreground state, and become fullscreen and active.

Parameters
poolRequestID

A unique identifier for this pooling request, this value must be passed to a call to poolComplete() when the application is finished any work necessary to be pooled.

Example usage in C++
void TestObject::onPooling( const QString &poolRequestID ) {
    // Do something here

    // Ensure you call the bb::Application::poolingComplete() method with the poolRequestID value.
}

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

    QObject::connect(&app, SIGNAL( pooling(const QString &) ), &testObject, SLOT( onPooling(const QString &) ));
See full example
Example usage in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.pooling.connect(onPooling);
    }
    
    function onPooling( poolRequestID ) {
        // Do work here
        Application.poolingComplete( poolRequestID );
    }
    // Other QML
}
Note:

This signal should not be used as the trigger for releasing resources and other heavy assets prior to the user leaving the application. Instead, the application should perform those actions when the processStateChanged(bb::ProcessType) signal arrives with a bb::ProcessState::Stopping value. These resources should be restored when the application becomes active.

,

If this pooling request does not have a corresponding call made to poolingComplete() (with the supplied poolRequestID) the application will be terminated instead.

,

A pooled process may still be terminated if necessary. For instance, if the device runs low on memory, pooled applications may be terminated to make memory available for other applications.

Since:

BlackBerry 10.0.0

void processStateChanged (

Emitted when the application is moved to a different process state.

Notifies the application when the process execution state has changed. The state will be one of the values enumerated by bb::ProcessState.

Parameters
processState

The new process state of the application.

Example usage in C++
void TestObject::onProcessStateChanged(bb::ProcessState::Type processState) {
    // Do something here
}

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

    QObject::connect(&app, SIGNAL( processStateChanged(bb::ProcessState::Type) ), &testObject, SLOT( onProcessStateChanged(bb::ProcessState::Type) ));
See full example
Example usage in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.processStateChanged.connect(onProcessStateChanged);
    }
    
    function onProcessStateChanged( processState ) {
        processStateChanged( processState );
    }
    // Other QML
}
Since:

BlackBerry 10.0.0

void swipeDown ()

Emitted when the Navigator detects a swipe down gesture.

Any slot attached to this signal is notified when the Navigator detects a swipe down gesture. Typically the application should display a menu in response to this gesture.

Example usage in C++
void TestObject::onSwipeDown() {
    // Do something here
}

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

    QObject::connect(&app, SIGNAL( swipeDown() ), &testObject, SLOT( onSwipeDown() ));
See full example
Example usage in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.swipeDown.connect(onSwipeDown);
    }
    
    function onSwipeDown() {
        processSwipeDown();
    }
    // Other QML
}
Since:

BlackBerry 10.0.0

void thumbnail ()

Emitted when the application has been thumbnailed.

Any slot attached to this signal is notified when your application is no longer fullscreen. This includes the application being thumbnailed on a swipe-up or a side-swipe to the task switcher.

The state of the application's main window group is considered to be the state of the Application as a whole.

Note:

If you connect to both this signal and windowGroupThumbnailed(const QString &) then you will receive duplicate notifications for the application's main window group.

Example usage in C++
void TestObject::onThumbnail() {
    // Do something here
}

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

    QObject::connect(&app, SIGNAL( thumbnail() ), &testObject, SLOT( onThumbnail() ));
See full example
Example use in QML
import bb.cascades 1.0

Page {
    // Once this object is created, attach the signal to a Javascript function.
    onCreationCompleted: {
        Application.thumbnail.connect(onThumbnailed);
    }
    
    function onThumbnailed() {
        applicationThumbnailed();
    }
    // Other QML
}
Since:

BlackBerry 10.0.0

void windowGroupAsleep (

Emitted when a window group becomes inactive.

Any slot attached to this signal is notified when a window group in an application becomes inactive. When this signal is received by an application, it should reduce CPU usage as much as possible with respect to the given window group.

Note:

If you connect to both this signal and asleep() then you will receive duplicate notifications for the application's main window group.

A window group ID of "none" should normally be treated as an event for the application's main window group.
Parameters
windowGroupID

The ID of the window group that is now inactive.

Since:

BlackBerry 10.0.0

void windowGroupAwake (

Emitted when a window group becomes active.

Any slot attached to this signal is notified when a window group in an application becomes active. When this signal is received, the application should resume all normal activity with respect to the given window group.

Note:

If you connect to both this signal and awake() then you will receive duplicate notifications for the application's main window group.

A window group ID of "none" should normally be treated as an event for the application's main window group.
Parameters
windowGroupID

The ID of the window group that is now active.

Since:

BlackBerry 10.0.0

void windowGroupFullscreen (

Emitted when a window group is restored to fullscreen status.

This signal is emitted when a window group in an application is restored to fullscreen, such as after being thumbnailed, or if it becomes the active application from the task switcher interface.

Note:

If you connect to both this signal and fullscreen() then you will receive duplicate notifications for the application's main window group.

A window group ID of "none" should normally be treated as an event for the application's main window group. This can happen because this event can occur before a window message has been processed by the application, which means the window group ID is not yet available in the framework.
Parameters
windowGroupID

The ID of the window group that is now fullscreen.

Since:

BlackBerry 10.0.0

void windowGroupInvisible (

Emitted when a window group is no longer visible.

Any slot attached to this signal is notified when a window group in the application is no longer visible.

Note:

If you connect to both this signal and invisible() then you will receive duplicate notifications for the application's main window group.

A window group ID of "none" should normally be treated as an event for the application's main window group.
Parameters
windowGroupID

The ID of the window group that is now invisible.

Since:

BlackBerry 10.0.0

void windowGroupThumbnailed (

Emitted when a window group has been thumbnailed.

Any slot attached to this signal is notified when a window group in the application is no longer fullscreen. This includes the application being thumbnailed on a swipe-up or a side-swipe to the task switcher.

Note:

If you connect to both this signal and thumbnail() then you will receive duplicate notifications for the application's main window group.

A window group ID of "none" should normally be treated as an event for the application's main window group.
Parameters
windowGroupID

The ID of the window group that has just been thumbnailed.

Since:

BlackBerry 10.0.0

void aboutToQuit ()Inherited

void unixSignal (
  • int)
Inherited

Last modified: 2014-09-30



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

comments powered by Disqus