Application

Since: BlackBerry 10.0.0

#include <bb/cascades/Application>

The class provides an event loop and handles application's menu scene, and main window.

Cascades applications must use this class and not QCoreApplication or QApplication.

The Application class provides an event loop and an event delivery mechanism for Cascades applications as well as providing the following properties:
  • scene : specifies the AbstractPane to be used as the scene for the main application window

  • cover : specifies the AbstractCover to be used when the application is in cover mode (also known as an Active frame)

  • menu : application Menu accessible by the user by the swipe from the top of the screen.

  • menuEnabled : whether the application Menu is enabled (it can be set to true even when menu isn't set so that it will provide the user with visual feedback that there's no menu)

  • mainWindow : provides access to an object representing applications's main Window

  • themeSupport : provides access to the theme used in the application

Cascades applications are not expected to subclass this class but instead instantiate it and invoke Application::exec() method to start the event loop. Creating Cascades controls and other ui elements is only supported after an instance of Application has been created. It must be created on the application's main thread.

An example of simple application:
#include <bb::cascades::Application>
#include <bb::cascades::Button>
#include <bb::cascades::Page>

using bb::cascades;

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

    Page *page = Page::create()
        .content(Button::create("Hello, World!"));
    app.setScene(page);

    return app.exec();
}

Here's an example of an equivalent QML-based application. Note that the document loading error checking is omitted (see QmlDocument for proper error checking).

// hello.qml file

Page {
    Button { text: "Hello, World!" }
}
// hello.cpp file

#include <bb::cascades::Application>
#include <bb::cascades::QmlDocument>
#include <bb::cascades::Page>

using bb::cascades;

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

    QmlDocument *qml = QmlDocument::create(&app, "hello.qml");
    Page *page = qml->createRootObject<Page>();
    app.setScene(page);

    return app.exec();
}

The Application instance is exposed to QML as a context property called "Application".

Here's an example of accessing the Application instance from QML:

Button {
    text: (Application.menuEnabled ? "Disable" : "Enable") 
            + " Application Menu"
    onClicked: Application.menuEnabled = !Application.menuEnabled;
}


Overview

Inheritance

QCoreApplication
bb::Application
bb::cascades::Application

QML properties

cover: bb::cascades::AbstractCover
mainWindow: bb::cascades::Window [read-only]
menu: bb::cascades::Menu
menuEnabled: bool
scene: bb::cascades::AbstractPane
themeSupport: bb::cascades::ThemeSupport [read-only]
applicationName: QStringInherited
applicationVersion: QStringInherited
autoExit: boolInherited
organizationDomain: QStringInherited
organizationName: QStringInherited

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 ()
bb::cascades::AbstractCover *cover () const
boolisMenuEnabled () const
bb::cascades::Window *mainWindow () const
bb::cascades::Menu *menu () const
Q_SLOT voidresetCover ()
Q_SLOT voidresetMenu ()
Q_SLOT voidresetMenuEnabled ()
Q_SLOT voidresetScene ()
QStringresolveAssetPath (const QUrl &url)
bb::cascades::AbstractPane *scene () const
Q_SLOT voidsetCover (bb::cascades::AbstractCover *cover)
Q_SLOT voidsetMenu (bb::cascades::Menu *menu)
Q_SLOT voidsetMenuEnabled (bool enabled)
Q_SLOT voidsetScene (bb::cascades::AbstractPane *scene)
bb::cascades::ThemeSupport *themeSupport () const
Q_INVOKABLE boolclearClosePrompt ()Inherited
voidderegisterWindowGroup (const QString &windowGroupID)Inherited
boolfilterEvent (void *message, long *result)Inherited
Q_INVOKABLE boolisAsleep () const Inherited
Q_INVOKABLE boolisAwake () const Inherited
Q_INVOKABLE boolisFullscreen () const Inherited
Q_INVOKABLE boolisInvisible () const Inherited
Q_INVOKABLE boolisThumbnailed () const Inherited
Q_INVOKABLE boolisWindowGroupAsleep (const QString &windowGroupID) const Inherited
Q_INVOKABLE boolisWindowGroupAwake (const QString &windowGroupID) const Inherited
Q_INVOKABLE boolisWindowGroupFullscreen (const QString &windowGroupID) const Inherited
Q_INVOKABLE boolisWindowGroupInvisible (const QString &windowGroupID) const Inherited
Q_INVOKABLE boolisWindowGroupThumbnailed (const QString &windowGroupID) const Inherited
virtual boolnotify (QObject *, QEvent *)Inherited
QCoreApplication (int &argc, char **argv, int=ApplicationFlags)Inherited
Q_INVOKABLE boolsetClosePrompt (const QString &title, const QString &message)Inherited
EventFiltersetEventFilter (EventFilter filter)Inherited
voidsetMainWindowGroup (const QString &mainWindowGroupID)Inherited

Static Public Functions Index

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

Only has inherited public slots

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

Signals Index

voidcoverChanged (bb::cascades::AbstractCover *cover)
voidmenuChanged (bb::cascades::Menu *menu)
voidmenuEnabledChanged (bool menuEnabledChanged)
voidsceneChanged (bb::cascades::AbstractPane *scene)
voidaboutToQuit ()Inherited
voidasleep ()Inherited
voidautoExitChanged (bool newAutoExit)Inherited
voidawake ()Inherited
voidfullscreen ()Inherited
voidinvisible ()Inherited
voidmanualExit ()Inherited
voidpooling (const QString &poolRequestID)Inherited
voidprocessStateChanged (bb::ProcessState::Type processState)Inherited
voidswipeDown ()Inherited
voidthumbnail ()Inherited
voidunixSignal (int)Inherited
voidwindowGroupAsleep (const QString &windowGroupID)Inherited
voidwindowGroupAwake (const QString &windowGroupID)Inherited
voidwindowGroupFullscreen (const QString &windowGroupID)Inherited
voidwindowGroupInvisible (const QString &windowGroupID)Inherited
voidwindowGroupThumbnailed (const QString &windowGroupID)Inherited

Public Types

(Only has inherited public types)

Encoding Inherited

CodecForTr
UnicodeUTF8
DefaultCodec = CodecForTr

typedef bool(* EventFilter Inherited

Properties

bb::cascades::AbstractCover cover

The cover of the application.

Since:

BlackBerry 10.0.0

bb::cascades::Window mainWindow[read-only]

Provides access to the main Window of the application.

Since:

BlackBerry 10.0.0

bb::cascades::Menu menu

The menu of the application displayed on the main window.

A menuChanged() signal is emitted when this property is changed.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

bool menuEnabled

The menu of the application displayed on the main window.

An application will typically disable the Menu to avoid conflicts with application behavior (such as the rubber band behavior of a ListView).

When the Menu is disabled, it will be completely hidden and there will be no rubber band animation indicating to the user that the swipe-down was successful.

If the property is set to false while the Menu is showing, it will be closed.

A menuEnabledChanged() signal is emitted when this property changes.

The default value of this property is true.

Since:

BlackBerry 10.0.0

bb::cascades::AbstractPane scene

The scene of the application.

The scene is displayed on the main window of the application.

A sceneChanged() signal is emitted when this property is changed.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

bb::cascades::ThemeSupport themeSupport[read-only]

Provides access to ThemeSupport, which is used to retrieve theme related information,.

ThemeSupport contains information about the application such as the color scheme used for controls.

Since:

BlackBerry 10.0.0

QString applicationNameInherited

QString applicationVersionInherited

bool autoExitInherited

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

Since:

BlackBerry 10.0.0

QString organizationDomainInherited

QString organizationNameInherited

Public Functions

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

Constructs an Application object.

Since:

BlackBerry 10.0.0

virtual~Application ()

Destructor.

The scene and menu are also destroyed if owned by the Application object.

Since:

BlackBerry 10.0.0

bb::cascades::AbstractCover * cover ()

Returns the cover used when the application is in cover mode.

Ownership of the returned object is not transferred.

Return:

The cover for this application or 0 if cover wasn't set.

Since:

BlackBerry 10.0.0

bool isMenuEnabled ()

Returns whether the Menu is enabled or not.

Return:

true if the Menu is enabled, false otherwise.

Since:

BlackBerry 10.0.0

bb::cascades::Window * mainWindow ()

Retrieves this application's main window.

Ownership of the returned object is not transferred.

Return:

The application's main window.

Since:

BlackBerry 10.0.0

bb::cascades::Menu * menu ()

Returns the Menu of the application.

Ownership of the returned object is not transferred.

Return:

The current application menu or 0 if one wasn't set.

Since:

BlackBerry 10.0.0

Q_SLOT void resetCover ()

Sets the value of cover property to the default value which is 0.

The replaced cover (if one was set) remains owned by its owner.

Since:

BlackBerry 10.0.0

Q_SLOT void resetMenu ()

Sets the value of menu property to the default value which is 0.

The replaced menu (if one was set) remains owned by its owner.

Since:

BlackBerry 10.0.0

Q_SLOT void resetMenuEnabled ()

Sets the value of menuEnabled property to the default value which is true.

Since:

BlackBerry 10.0.0

Q_SLOT void resetScene ()

Sets the value of scene property to the default value which is 0.

The replaced scene (if one was set) remains owned by its owner.

If the replaced scene (if one was set) is owned by the Application it will be deleted.

Since:

BlackBerry 10.0.0

QString resolveAssetPath (

Retrieves a resolved asset path, given a file name.

Assets stored according to design unit selector principles can be resolved with this method, which is useful when developing c++ applications.

Parameters
url

The filename to resolve.

Return:

A QString holding the full path to the file.

Since:

BlackBerry 10.3.0

bb::cascades::AbstractPane * scene ()

Returns the scene associated with the main window.

Ownership of the returned object is not transferred.

Return:

pane serving as the scene for the main window or 0 if scene wasn't set.

Since:

BlackBerry 10.0.0

Q_SLOT void setCover (

Sets the cover to be used when the application is in cover mode.

The Application object takes ownership of the passed AbstractCover unless it already has a parent.

The default cover will take a screenshot of the whole application and scale it down to cover mode.

If the replaced cover (if one was set) is owned by the Application it will be deleted, if not its ownership doesn't change. If it already has another parent the caller MUST ensure that setCover(0) is called before the cover object is deleted.

Parameters
cover

The cover to be used or 0 to remove current cover.

Since:

BlackBerry 10.0.0

Q_SLOT void setMenu (

Sets the application Menu.

The application will take ownership of the Menu if it doesn't have a parent.

If the replaced menu (if one was set) is owned by the application it will be deleted, otherwise its ownership doesn't change.

Parameters
menu

The new menu or 0 to remove the menu.

Since:

BlackBerry 10.0.0

Q_SLOT void setMenuEnabled (
  • boolenabled)

Enables or disables the Menu.

An application will typically disable the Menu to avoid conflicts with application behavior (such as the rubber band behavior of a ListView).

When the Menu is disabled, it will be completely hidden and there will be no rubber band animation indicating to the user that the swipe-down was successful. If the enabled property is set to false while the Menu is showing, it will be closed.

Parameters
enabled

If true the Menu should be enabled, if false the Menu should be disabled.

Since:

BlackBerry 10.0.0

Q_SLOT void setScene (

Sets the root Pane for the application.

The Application object takes ownership of the passed pane unless it already has a parent.

If the replaced scene (if one was set) is owned by the Application it will be deleted, if not its ownership doesn't change. If it already has another parent the caller MUST ensure that setScene(0) is called before the scene object is deleted.

Parameters
scene

The pane to be used as a scene or 0 to remove current scene.

Since:

BlackBerry 10.0.0

bb::cascades::ThemeSupport * themeSupport ()

Retrieves the ThemeSupport object.

Ownership of the returned object is not transferred.

Return:

The application's ThemeSupport object.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool clearClosePrompt ()Inherited

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 (Inherited

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

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

Q_INVOKABLE bool isAsleep ()Inherited

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 ()Inherited

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 ()Inherited

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 ()Inherited

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 ()Inherited

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 (Inherited

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 (Inherited

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 (Inherited

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 (Inherited

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 (Inherited

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

virtual bool notify (Inherited

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

Q_INVOKABLE bool setClosePrompt (Inherited

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

EventFilter setEventFilter (
  • EventFilterfilter)
Inherited

void setMainWindowGroup (Inherited

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

Static Public Functions

Application * instance ()

Retrieves the application instance.

The application must be instantiated first or 0 will be returned with a warning printout.

Return:

A pointer to the pplication instance or 0 if the Application has not been instantiated.

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

(Only has inherited public slots)

bool autoExit ()Inherited

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 ()Inherited

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 ()Inherited

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 (Inherited

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

void quit ()Inherited

bool requestExit ()Inherited

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)
Inherited

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 (Inherited

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

Signals

void coverChanged (

Emitted when the cover for this application is changed.

Parameters
cover

A new cover or 0 if one was removed.

Since:

BlackBerry 10.0.0

void menuChanged (

Emitted when the menu is changed.

Parameters
menu

A new menu or 0 if one was removed.

Since:

BlackBerry 10.0.0

void menuEnabledChanged (
  • boolmenuEnabledChanged)

Emitted when the menuEnabled property changed.

Parameters
menuEnabledChanged

true if the menu was enabled, false otherwise.

Since:

BlackBerry 10.0.0

void sceneChanged (

Emitted when the main window's scene is changed.

Parameters
scene

A new scene or 0 if one was removed.

Since:

BlackBerry 10.0.0

void aboutToQuit ()Inherited

void asleep ()Inherited

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)
Inherited

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 ()Inherited

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 ()Inherited

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 ()Inherited

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 ()Inherited

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 (Inherited

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 (Inherited

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 ()Inherited

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 ()Inherited

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 unixSignal (
  • int)
Inherited

void windowGroupAsleep (Inherited

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 (Inherited

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 (Inherited

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 (Inherited

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 (Inherited

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

Last modified: 2014-06-24



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

comments powered by Disqus