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.
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.
#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 | : QString![]() |
applicationVersion | : QString![]() |
autoExit | : bool![]() |
organizationDomain | : QString![]() |
organizationName | : QString![]() |
QML signals
onCoverChanged | : {} |
onMenuChanged | : {} |
onMenuEnabledChanged | : {} |
onSceneChanged | : {} |
onAboutToQuit | ![]() |
onAsleep | ![]() |
onAutoExitChanged | ![]() |
onAwake | ![]() |
onFullscreen | ![]() |
onInvisible | ![]() |
onManualExit | ![]() |
onPooling | ![]() |
onProcessStateChanged | ![]() |
onSwipeDown | ![]() |
onThumbnail | ![]() |
onUnixSignal | ![]() |
onWindowGroupAsleep | ![]() |
onWindowGroupAwake | ![]() |
onWindowGroupFullscreen | ![]() |
onWindowGroupInvisible | ![]() |
onWindowGroupThumbnailed | ![]() |
Public Types Index
Only has inherited public types
enum EncodingCodecForTr, UnicodeUTF8, DefaultCodec CodecForTr | |
bool(* | EventFilter |
Properties Index
Public Functions Index
Application (int &argc, char **argv) | |
virtual | ~Application () |
bb::cascades::AbstractCover * | cover () const |
bool | isMenuEnabled () const |
bb::cascades::Window * | mainWindow () const |
bb::cascades::Menu * | menu () const |
Q_SLOT void | resetCover () |
Q_SLOT void | resetMenu () |
Q_SLOT void | resetMenuEnabled () |
Q_SLOT void | resetScene () |
QString | resolveAssetPath (const QUrl &url) |
bb::cascades::AbstractPane * | scene () const |
Q_SLOT void | setCover (bb::cascades::AbstractCover *cover) |
Q_SLOT void | setMenu (bb::cascades::Menu *menu) |
Q_SLOT void | setMenuEnabled (bool enabled) |
Q_SLOT void | setScene (bb::cascades::AbstractPane *scene) |
void | startKeyEventProcessing () |
bb::cascades::ThemeSupport * | themeSupport () const |
Q_INVOKABLE bool | clearClosePrompt ()![]() |
void | deregisterWindowGroup (const QString &windowGroupID)![]() |
bool | filterEvent (void *message, long *result)![]() |
Q_INVOKABLE bool | isAsleep () const ![]() |
Q_INVOKABLE bool | isAwake () const ![]() |
Q_INVOKABLE bool | isFullscreen () const ![]() |
Q_INVOKABLE bool | isInvisible () const ![]() |
Q_INVOKABLE bool | isThumbnailed () const ![]() |
Q_INVOKABLE bool | isWindowGroupAsleep (const QString &windowGroupID) const ![]() |
Q_INVOKABLE bool | isWindowGroupAwake (const QString &windowGroupID) const ![]() |
Q_INVOKABLE bool | isWindowGroupFullscreen (const QString &windowGroupID) const ![]() |
Q_INVOKABLE bool | isWindowGroupInvisible (const QString &windowGroupID) const ![]() |
Q_INVOKABLE bool | isWindowGroupThumbnailed (const QString &windowGroupID) const ![]() |
virtual bool | notify (QObject *, QEvent *)![]() |
QCoreApplication (int &argc, char **argv, int=ApplicationFlags)![]() | |
Q_INVOKABLE bool | setClosePrompt (const QString &title, const QString &message)![]() |
EventFilter | setEventFilter (EventFilter filter)![]() |
void | setMainWindowGroup (const QString &mainWindowGroupID)![]() |
Static Public Functions Index
Application * | instance () |
void | addLibraryPath (const QString &)![]() |
QString | applicationDirPath ()![]() |
QString | applicationFilePath ()![]() |
QString | applicationName ()![]() |
qint64 | applicationPid ()![]() |
QString | applicationVersion ()![]() |
QStringList | arguments ()![]() |
bool | closingDown ()![]() |
int | exec ()![]() |
void | exit (int retcode=0)![]() |
void | flush ()![]() |
bool | hasPendingEvents ()![]() |
void | installTranslator (QTranslator *messageFile)![]() |
QStringList | libraryPaths ()![]() |
QString | organizationDomain ()![]() |
QString | organizationName ()![]() |
void | postEvent (QObject *receiver, QEvent *event)![]() |
void | postEvent (QObject *receiver, QEvent *event, int priority)![]() |
void | processEvents (QEventLoop::ProcessEventsFlags flags=QEventLoop::AllEvents)![]() |
void | processEvents (QEventLoop::ProcessEventsFlags flags, int maxtime)![]() |
void | removeLibraryPath (const QString &)![]() |
void | removePostedEvents (QObject *receiver)![]() |
void | removePostedEvents (QObject *receiver, int eventType)![]() |
void | removeTranslator (QTranslator *messageFile)![]() |
bool | sendEvent (QObject *receiver, QEvent *event)![]() |
void | sendPostedEvents (QObject *receiver, int event_type)![]() |
void | sendPostedEvents ()![]() |
void | setApplicationName (const QString &application)![]() |
void | setApplicationVersion (const QString &version)![]() |
void | setAttribute (Qt::ApplicationAttribute attribute, bool on=true)![]() |
void | setLibraryPaths (const QStringList &)![]() |
void | setOrganizationDomain (const QString &orgDomain)![]() |
void | setOrganizationName (const QString &orgName)![]() |
bool | startingUp ()![]() |
bool | testAttribute (Qt::ApplicationAttribute attribute)![]() |
QString | translate (const char *context, const char *key, const char *disambiguation=0, Encoding encoding=CodecForTr)![]() |
QString | translate (const char *context, const char *key, const char *disambiguation, Encoding encoding, int n)![]() |
Protected Functions Index
Only has inherited protected functions
virtual bool | compressEvent (QEvent *, QObject *receiver, QPostEventList *)![]() |
virtual bool | event (QEvent *)![]() |
QCoreApplication (QCoreApplicationPrivate &p)![]() |
Public Slots Index
Only has inherited public slots
bool | autoExit () const ![]() |
bool | extendTerminationTimeout ()![]() |
bool | minimize ()![]() |
void | poolingComplete (const QString &poolRequestID) const ![]() |
void | quit ()![]() |
bool | requestExit ()![]() |
void | setAutoExit (bool autoExit)![]() |
bool | setIconBadge (bb::IconBadge::Type badge)![]() |
Signals Index
void | coverChanged (bb::cascades::AbstractCover *cover) |
void | menuChanged (bb::cascades::Menu *menu) |
void | menuEnabledChanged (bool menuEnabledChanged) |
void | sceneChanged (bb::cascades::AbstractPane *scene) |
void | aboutToQuit ()![]() |
void | asleep ()![]() |
void | autoExitChanged (bool newAutoExit)![]() |
void | awake ()![]() |
void | fullscreen ()![]() |
void | invisible ()![]() |
void | manualExit ()![]() |
void | pooling (const QString &poolRequestID)![]() |
void | processStateChanged (bb::ProcessState::Type processState)![]() |
void | swipeDown ()![]() |
void | thumbnail ()![]() |
void | unixSignal (int)![]() |
void | windowGroupAsleep (const QString &windowGroupID)![]() |
void | windowGroupAwake (const QString &windowGroupID)![]() |
void | windowGroupFullscreen (const QString &windowGroupID)![]() |
void | windowGroupInvisible (const QString &windowGroupID)![]() |
void | windowGroupThumbnailed (const QString &windowGroupID)![]() |
Public Types
(Only has inherited public types)
- CodecForTr
- UnicodeUTF8
- DefaultCodec CodecForTr
typedef bool(* 
Properties
bb::cascades::Window
Provides access to the main Window of the application.
BlackBerry 10.0.0
bb::cascades::AbstractPane
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.
BlackBerry 10.0.0
bb::cascades::ThemeSupport
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.
BlackBerry 10.0.0
bool
The auto exit flag, for controlling the behavior of an exiting application.
BlackBerry 10.0.0
Public Functions
virtual
Destructor.
The scene and menu are also destroyed if owned by the Application object.
BlackBerry 10.0.0
bb::cascades::AbstractCover *
Returns the cover used when the application is in cover mode.
Ownership of the returned object is not transferred.
The cover for this application or 0 if cover wasn't set.
BlackBerry 10.0.0
bb::cascades::Window *
Retrieves this application's main window.
Ownership of the returned object is not transferred.
The application's main window.
BlackBerry 10.0.0
Q_SLOT void
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.
BlackBerry 10.0.0
Q_SLOT void
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.
BlackBerry 10.0.0
QString
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. |
A QString holding the full path to the file.
BlackBerry 10.3.0
bb::cascades::AbstractPane *
Returns the scene associated with the main window.
Ownership of the returned object is not transferred.
pane serving as the scene for the main window or 0 if scene wasn't set.
BlackBerry 10.0.0
Q_SLOT void
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. |
BlackBerry 10.0.0
Q_SLOT void
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. |
BlackBerry 10.0.0
void
After startup, tell Cascades to start processing key events.
If the key buffering policy is set to UntilTold in the application manifest, this API is used to start the event processing. Typically the app would want to wait for the expected control to be focused at startup, and then call this API. Once input processing has started, subsequent calls to this API has no effect. Likewise if the key buffering policy is set to anything other than UntilTold.
This does only affect devices with physical keyboards.
In addition to key events, this also affects trackpad events and capacitive keyboard events, since they follow the same propagation rules in other aspects.
BlackBerry 10.3.2
bb::cascades::ThemeSupport *
Retrieves the ThemeSupport object.
Ownership of the returned object is not transferred.
The application's ThemeSupport object.
BlackBerry 10.0.0
Q_INVOKABLE bool 
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.
#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 } }
true if the close prompt was cleared, false otherwise.
BlackBerry 10.0.0
void 
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. |
BlackBerry 10.0.0
bool 
Q_INVOKABLE bool 
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.
true if the main window group for the application is currently inactive, false otherwise.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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.
true if the main window group for the application is currently active, false otherwise.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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.
true if the main window group for the application is currently fullscreen, false otherwise.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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.
true if the main window group for the application is currently invisible, false otherwise.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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.
true if the main window group for the application is currently thumbnailed, false otherwise.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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. |
true if the supplied window group is currently inactive, false otherwise. If the window group is not recognized, this method returns false.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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. |
true if the supplied window group is currently active, false otherwise. If the window group ID is not recognized, this method returns false.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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. |
true if the supplied window group is currently fullscreen, false otherwise. If the window group is not recognized, this method return false.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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. |
true if the supplied window group is currently invisible, false otherwise. If the window group is not recognized, this method returns false.
BlackBerry 10.2.0
Q_INVOKABLE bool 
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. |
true if the supplied window group is currently thumbnailed, false otherwise. If the window group is not recognized, this method returns false.
BlackBerry 10.2.0
virtual bool 
Q_INVOKABLE bool 
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 '\'.
#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. |
true if the close prompt was set, false otherwise.
BlackBerry 10.0.0
EventFilter 
void 
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. |
BlackBerry 10.0.0
Static Public Functions
Application *
Retrieves the application instance.
The application must be instantiated first or 0 will be returned with a warning printout.
A pointer to the Application instance or 0 if the Application has not been instantiated.
BlackBerry 10.0.0
void 
qint64 
bool 
int 
void 
void 
bool 
void 
void 
void 
void 
void 
void 
void 
void 
void 
bool 
void 
void 
void 
void 
void 
void 
void 
void 
bool 
bool 
Protected Functions
(Only has inherited protected functions)
virtual bool 
virtual bool 
Public Slots
(Only has inherited public slots)
bool 
Returns the value of the auto exit flag.
The flag is set using the setAutoExit(bool) method.
#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 } }
The value of the auto exit flag.
BlackBerry 10.0.0
bool 
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.
#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 } }
true if the request to extend the timeout was successful, false otherwise.
BlackBerry 10.0.0
bool 
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.
#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 } }
true if the minimize request was successfully sent, false otherwise.
BlackBerry 10.0.0
void 
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. |
BlackBerry 10.0.0
void 
bool 
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.
In general, applications should not programmatically exit. They should terminate only when explicitly closed by the end user.
#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 }
true if the close request was successfully sent, false otherwise.
BlackBerry 10.0.0
void 
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.
#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. |
BlackBerry 10.0.0
bool 
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.
#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. |
true if the badge was successfully applied, false otherwise.
BlackBerry 10.0.0
Signals
void
Emitted when the cover for this application is changed.
Parameters | |
---|---|
cover |
A new cover or 0 if one was removed. |
BlackBerry 10.0.0
void
Emitted when the main window's scene is changed.
Parameters | |
---|---|
scene |
A new scene or 0 if one was removed. |
BlackBerry 10.0.0
void 
void 
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.
If you connect to both this signal and windowGroupAsleep(const QString &) then you will receive duplicate notifications for the application's main window group.
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
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 }
BlackBerry 10.0.0
void 
Emitted when the auto exit flag changes.
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
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. |
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and windowGroupAwake(const QString &) then you will receive duplicate notifications for the application's main window group.
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
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 }
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and windowGroupFullscreen(const QString &) then you will receive duplicate notifications for the application's main window group.
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
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 }
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and windowGroupInvisible(const QString &) then you will receive duplicate notifications for the application's main window group.
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
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 }
BlackBerry 10.0.0
void 
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.
setAutoExit(bool) for more details on handling application exit.
void TestObject::onManualExit() { // Handle exit explicitly. // Make sure to exit the application at the end. } int main(int argc, char **argv) { bb::Application app(argc, argv); TestObject testObject; // The manualExit signal will not be emitted unless auto exit flag set to false. app.setAutoExit(false); QObject::connect(&app, SIGNAL( manualExit() ), &testObject, SLOT( onManualExit() ));See full example
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. }
BlackBerry 10.0.0
void 
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. |
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
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 }
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.
BlackBerry 10.0.0
void 
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. |
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
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 }
BlackBerry 10.0.0
void 
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.
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
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 }
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and windowGroupThumbnailed(const QString &) then you will receive duplicate notifications for the application's main window group.
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
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 }
BlackBerry 10.0.0
void 
void 
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.
If you connect to both this signal and asleep() then you will receive duplicate notifications for the application's main window group.
Parameters | |
---|---|
windowGroupID |
The ID of the window group that is now inactive. |
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and awake() then you will receive duplicate notifications for the application's main window group.
Parameters | |
---|---|
windowGroupID |
The ID of the window group that is now active. |
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and fullscreen() then you will receive duplicate notifications for the application's main window group.
Parameters | |
---|---|
windowGroupID |
The ID of the window group that is now fullscreen. |
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and invisible() then you will receive duplicate notifications for the application's main window group.
Parameters | |
---|---|
windowGroupID |
The ID of the window group that is now invisible. |
BlackBerry 10.0.0
void 
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.
If you connect to both this signal and thumbnail() then you will receive duplicate notifications for the application's main window group.
Parameters | |
---|---|
windowGroupID |
The ID of the window group that has just been thumbnailed. |
BlackBerry 10.0.0