It seems like the browser you are using has JavaScript disabled. As a result, the site will not function properly. We really want you to enable it so you may experience our site as we intended it. If you have no idea what we are talking about or if you need help, visit http://www.enable-javascript.com×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

Oops, it seems like you're using an old browser that we do not fully support. If you're able to, please upgrade your browser here.×
This website uses cookies. By continuing to browse this site you are agreeing to our use of cookies. Find out more on our cookie page.×

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.

Q_SLOT voidsetCover (

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.

Q_SLOT voidsetMenuEnabled (

boolenabled)

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

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.

Q_INVOKABLE boolclearClosePrompt()

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.

voidderegisterWindowGroup (

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

boolfilterEvent (

void *message,

long *result )

Q_INVOKABLE boolisAsleep()

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

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

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

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

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

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

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

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

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

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.

virtual boolnotify (

QCoreApplication (

int &argc,

char **argv,

int )

Q_INVOKABLE boolsetClosePrompt (

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 '\'.

EventFiltersetEventFilter (

EventFilterfilter)

voidsetMainWindowGroup (

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

boolextendTerminationTimeout()

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.

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

Since:

BlackBerry 10.0.0

boolminimize()

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.

voidpoolingComplete (

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.

voidquit()

boolrequestExit()

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.

voidsetAutoExit (

boolautoExit)

Sets the behavior for an exiting application.

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

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

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

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

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

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

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

voidsceneChanged (

voidaboutToQuit()

voidasleep()

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.

voidinvisible()

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.

voidmanualExit()

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.

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

voidpooling (

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.

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.

voidunixSignal (

int)

voidwindowGroupAsleep (

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

voidwindowGroupAwake (

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.

voidwindowGroupFullscreen (

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.

voidwindowGroupThumbnailed (

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: 2015-01-22

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

1. Choose your focus

This is the focus controller. Use this controller to choose your primary development approach (Cascades or Core).

By selecting a focus, you get to decide what content should be front and center on the site.

2. Download the tools

Before you start developing, you'll need to visit the Downloads tab. Here you'll find downloads for the BlackBerry 10 Native SDK, BlackBerry 10 Device Simulator, and some other useful tools.

3. Try the sample apps

Now featuring a filter control, the Sample apps tab allows you to search for samples by name or by feature.

Select either the Core or Cascades check boxes to display the samples relevant to your focus.

4. Educate yourself

The Documentation tab contains tons of examples, tutorials, and best practices to guide you along the path towards building an awesome app.

The documentation for your preferred focus always appears at the top of the left-hand navigation, but you can still access the rest of the documentation at the bottom.

5. Start developing

The Reference tab is where you'll find essential details about how to use our APIs.

You can use the left-hand navigation to choose how you would like to browse the reference: by module, by topic, or alphabetically. If you have an idea of what you are looking for, start typing it in the Filter box.