Notifications
From WebOS101
Contents |
Banner Notifications
Introduction
Banner notifications are the simplest form of notifications, as they don't require their own stage and are easy to construct. For the details on the showBanner function, see AppController.showBanner.
Creating A Banner
The most basic notification is a line of text (which is truncated to fit the screen width) and a scaled version of the application's icon which is shown immediately to the left of the message. An example of an app using banner notifications can be seen at http://i650.photobucket.com/albums/uu229/kesne/checkers_2010-30-06_125940.png (the application is Checkers, available at http://developer.palm.com/appredirect/?packageid=net.keenstudios.app.checkers)
This type of notification can be created by using the following line of code, replacing "Banner Text" with your desired text to show.
Mojo.Controller.getAppController().showBanner("Banner Text", {source: 'notification'});
using the Enyo framework is just as easy:
enyo.windows.addBannerMessage("Banner Text", '{}');
If the user taps the message, the framework will relaunch your application by calling its handleLaunch method. This is true whether your application is maximized, minimized, or closed. The second argument in the arguments list above is used to pass launch parameters to your application.
There is an optional third argument, called category, which can be used to manage sequences of notifications. Since banner notifications must display for a fixed period of time, they will queue up if there are more notifications than can be displayed within a given period of time. If there is more than one banner notification queued within a specific category, the framework will discard all the but the most recent one. By default all banner notifications belong to the category 'banner' so if you want to avoid having your notifications replaced by other default banners, or if you have multiple notification streams to manage, you will want to define a category for your notifications.
Applications should only use banner notifications when not in focus, either minimized (with a card view but not the foreground card) or in the background (without a card stage). Typically the banner should be followed by a Dashboard stage if the user doesn't tap on the banner, so that it appears that the Dashboard is a reminder of the ignored banner. However, neither of these guidelines are enforced by the framework.
Pop-up Notifications
A pop-up notification is very similar to a dashboard notification, as it is interactive, but it does not stay in the notification area and continue to be active. A Pop-up notification guarantees the users attention, but can be intrusive, so you should use it sparingly. The cores system uses pop-up notifications for incoming phone calls, imminent calendar events, phone plugged in, low memory or battery low condition. An example of an app using pop-up notifications can be seen at http://i650.photobucket.com/albums/uu229/kesne/checkers_2010-30-06_133350.png (the application is Checkers, available at http://developer.palm.com/appredirect/?packageid=net.keenstudios.app.checkers)
You can create a pop-up notification by creating a stage and pushing a pop-up scene onto it.
var appController = Mojo.Controller.getAppController();
var pushPopup = function(stageController) {
stageController.pushScene('myPopup', "Warning, warning, everybody to get from street!");
};
appController.createStageWithCallback({name: "popupStage", lightweight: true, height: 305}, pushPopup, 'popupalert');
You can see that this is a simple version of the create stage function, where the callback is defined pushPopup, and then createStageWithCallback() creates the stage and sets up the callback.
Where pop-ups and dashboards differ is the option to set the height property, instead of using the default value. The default is 200 pixels on the Pre, but will be adjusted on other devices to scale appropriately. Use "popupalert" as the last argument to indicate that this is a pop-up stage. As in the general case, you specify the stage name and lightweight properties and include the callback function as the second argument.
You can do most anything within a pop-up scene that you can do in any other scene, but UI conventions dictate that you limit your actions to simple messages and selections. The only critical action is that your pop-up assistant must close the window on exit to close the stage and remove it from the display. You can do this by calling the close function.
this.controller.window.close();
For more details on using multiple stages in applications, see Multi-Stage Applications
