A web icon is an application that launches a BlackBerry
smartphone browser to a predefined web address. Web icons are displayed
in the list of BlackBerry smartphone applications and they can be
used as shortcuts to a BlackBerry smartphone user's favorite web
sites.
The source code for creating web icons in this article can
also be downloaded here.
To create a web icon you must perform the following:
- Create a new class that extends from
WebIcon.
- Change the package name on all classes.
- Set the title of your application.
- Add an application icon.
Task 1 - Create a new class that extends from WebIcon
BlackBerry Device Software earlier than 4.0
When using BlackBerry® Device Software versions earlier than
4.0, the default browser is the only one that can be invoked.
// NOTE: You MUST change the package name to reflect
your company name
// package com.acme.blackberry.webicon;
import net.rim.device.api.system.Application;
import net.rim.device.api.system.CodeModuleManager;
import net.rim.device.api.system.ApplicationDescriptor;
import net.rim.device.api.system.ApplicationManager;
import net.rim.device.api.system.ApplicationManagerException;
public class WebIcon
{
public final static int DEFAULT_BROWSER = 0;
/*
* Launches the default browser to the given url for devices pre-software
* version 4.0
*
* @param String URL
* @param BrowserSession browserSession
*/
private static void launchBrowser(int browserType, String url)
{
int moduleHandle =
CodeModuleManager.getModuleHandle("net_rim_bb_browser_daemon");
if (moduleHandle > 0)
{
// Use the default browser application descriptor
as
// the model descriptor.
ApplicationDescriptor[] browserDescriptors =
CodeModuleManager.getApplicationDescriptors(moduleHandle);
// Create the new application descriptor.
String[] args = {"url", url, null};
// Turn off auto restart (the original descriptor
// has it turned on) so we don't end up in a never
// ending loop of restarting the browser.
int flags = browserDescriptors[0].getFlags() ^
ApplicationDescriptor.FLAG_AUTO_RESTART;
ApplicationDescriptor newDescriptor =
new ApplicationDescriptor
(
browserDescriptors[0],
"BrowserPS",
args,
null,
-1,
null,
-1,
flags
);
// Run the application.
try
{
ApplicationManager.getApplicationManager().
runApplication(newDescriptor);
}
catch (ApplicationManagerException ame)
{
System.err.println(ame.toString());
}
}
}
}
As an example, a new class called BlackBerryWebIcon is
created below that extends WebIcon and points to the
BlackBerry.com web site. Only three lines of code need to be added
to the main method of this new class.
// NOTE: You MUST change the package name to reflect
your company
// name package com.acme.blackberry.webicon;
public class BlackBerryWebIcon extends WebIcon
{
public static void main(String[] args)
{
BlackBerryWebIcon webIcon = new BlackBerryWebIcon();
webIcon.launchBrowser(DEFAULT_BROWSER, "http://www.blackberry.com");
webIcon.close();
}
}
BlackBerry Device Software 4.0 and later
The previous sample can also be used for BlackBerry Device
Software up to and including 4.2.1, although the following code
samples offer a simpler methodology for allowing the web icon to
invoke the default browser or invoke specific browsers on the BlackBerry smartphone.
A web icon may invoke either the default browser on the BlackBerry
smartphone, or the Internet Browser, the Wireless Application Protocol
(WAP) Browser, the BlackBerry® Browser, the Wi-Fi® Browser, or the
BlackBerry® Unite!™ Browser.
The following code creates a web icon that launches a browser
to a specific web address for the given browser type. If the given
browser type is not available, the web icon launches the default
browser.
// NOTE: You MUST change the package name to reflect
your company
// name package com.acme.blackberry.webicon;
import net.rim.device.api.system.Application;
import net.rim.blackberry.api.browser.BrowserSession;
/**
* This class allows easy access for launching a browser for
* devices 4.0 and later
*/
class WebIcon extends Application
{
public static final int DEFAULT_BROWSER = 0;
public static final int WAP_BROWSER = 1;
public static final int BES_BROWSER = 2;
public static final int WIFI_BROWSER = 3;
public static final int BIS_BROWSER = 4;
public static final int UNITE_BROWSER = 5;
/*
* Attempts to launch the given browser to the given url.
* If launching this browser is not successful then the
* default browser will be launched.
*
* @param int browserType
* @param String url
*/
public void launchBrowser(int browserType, String url)
{
BrowserSession browserSession = createBrowserSession(browserType);
browserSession.displayPage(url);
// The following line is a work around to the issue
found in
// version 4.2.0. If you are coding for a device pre
4.2,
// comment the following line out.
// browserSession.showBrowser();
}
/*
* Attempts to create a browser session of a specific type given.
* If the system is unable to create the given browser
session
* then the default browser will be launched.
*
* @param int browserType
* @return BrowserSession
*/
private BrowserSession createBrowserSession(int browserType)
{
String uid = null;
BrowserSession browserSession = null;
switch (browserType)
{
case BIS_BROWSER:
{
browserSession =
BrowserSessionFactory.createBISBrowserSession();
break;
}
case WAP_BROWSER:
{
browserSession =
BrowserSessionFactory.createWAPBrowserSession();
break;
}
case BES_BROWSER:
{
browserSession =
BrowserSessionFactory.createBESBrowserSession();
break;
}
case WIFI_BROWSER:
{
browserSession =
BrowserSessionFactory.createWiFiBrowserSession();
break;
}
case UNITE_BROWSER:
{
browserSession =
BrowserSessionFactory.createUniteBrowserSession();
break;
}
}
return null == browserSession ?
BrowserSessionFactory.createDefaultBrowserSession()
:
browserSession;
}
}
Note: The previous code sample makes static calls to a factory class
called BrowserSessionFactory to create these different BrowserSessions.
It can be found in DB-00701 or
in the attached zip
file.
Note: BlackBerry Device Software 4.2 may prevent the previous code
sample from opening the default browser. As a workaround, add the
following code after the call to the displayPage method.
This issue was resolved in BlackBerry Device Software 4.2.1.
// Get the default session browserSession
browserSession = Browser.getDefaultSession();
// now launch the URL
browserSession.displayPage("http://www.BlackBerry.com");
// The following line is a work around to the issue found
in
// version 4.2.0
browserSession.showBrowser();
As an example, a new class called BlackBerryWebIcon is
created in the following sample that extends WebIcon and
points to the BlackBerry.com website. Again, only three lines of
code need to be added to this new class.
// NOTE: You MUST change the package name to reflect
your company
// name package com.acme.blackberry.webicon;
Public class BlackBerryWebIcon extends WebIcon
{
public static void main(String[] args)
{
BlackBerryWebIcon webIcon = new BlackBerryWebIcon();
webIcon.launchBrowser(DEFAULT_BROWSER, "http://www.blackberry.com");
webIcon.close();
}
}
Task 2 - Change the package name on all classes
Change the package name in all Java files in your project
so that the code will be unique to your organization. It is common
practice to begin the package name with com.[your company
name].[project name].
Task 3 - Set the title of your application
To set the title, right-click the project, select Properties and
then select the General tab. In this area, you can
type the application title, vendor name and application description.
Note: This title is what appears on the Home screen of the BlackBerry
smartphone when the BlackBerry smartphone user scrolls over the
icon.
Task 4 - Add an application icon
Add your own custom icon for the application. This is the
icon that displays on the Home screen of the BlackBerry smartphone.
To do this, complete the following steps:
- Locate or create an icon using any standard
image editing tool. The image should be approximately 32 x 32 pixels
in size.
- Right-click the project, select Add File to Project,
and then navigate to the custom icon.
- Once the file is added, right-click the file, and then
select Properties.
- Select the check box for Use as Application Icon.
Note: For information on defining an application icon, see DB-00126.