You may have noticed how certain strings are underlined in native BlackBerry smartphone applications. For example, phone numbers are underlined or highlighted when composing or reading messages. Once selected, these special strings are assigned a context-sensitive menu item, for example call a phone number. Third-party applications can take advantage of this functionality to add custom context-sensitive menu items to standard BlackBerry smartphone applications. These menu items can be used to launch a custom application, open the BlackBerry® Browser to a specific URL, send a message, or do any number of other things.
This functionality can be achieved by using one of two application programming interfaces (APIs):
net.rim.device.api.util.StringPattern - This API was introduced in BlackBerry Device Software 4.0 and requires you to implement your own string matching algorithm.
net.rim.blackberry.api.stringpattern.PatternRepository - This API was introduced in BlackBerry Device Software 4.3.0, and allows the use of Perl style regular expressions.
The samples provided in this article match a United States zip code and allow the BlackBerry smartphone user to lookup more information on the zip code.
The StringPattern source code example uses the string pattern matching that was introduced in BlackBerry Device Software 4.0. It requires implementing another string matching algorithm.
There are four major components required for this implementation
net.rim.device.api.util.StringPattern - This class represents the pattern that you want to recognize. It can be as simple as a zip code, or as complex as an address in its various forms. To write an effective StringPattern, remember that each character typed into the applicable field will be parsed by your implementation. As such, efficiency is important in this class.
net.rim.device.api.ui.component.MenuItem - The MenuItem includes the majority of the implementation for this capability. The MenuItem typically includes or references the action that will occur once a match is found and invoked by the BlackBerry smartphone user. For example, the run method for the MenuItem is invoked when a zip code has been recognized and the BlackBerry smartphone user selects the Lookup Zipcode menu item.
net.rim.device.api.ui.component.ActiveFieldCookie - The ActiveFieldCookie is a container object that allows the StringPattern class to transfer the context-sensitive information to the MenuItem. It also allows the implementation to add the appropriate menu item, or multiple menu items, when a string pattern match is found.
net.rim.device.api.util.Factory - The implementation of the Factory class links the StringPattern to the ActiveFieldCookie when a match is recorded in the StringPattern implementation. Typically, the Factory implementation is quite compact but a necessary requirement for the system.
The ZipCodeLookupSample class provides the starting point for the application. The application is configured as an auto-start system module so that all of the components can be registered upon start up. It is important to note that the main class initializes all of the required components described above, and has been implemented carefully to only initialize these components once.
The PatternRepository source code sample uses the API that was introduced in BlackBerry Device Software 4.3.0 and allows the use of regular expressions for string matching, which makes the sample much simpler than the prior sample.
There are two major components required for this implementation
net.rim.blackberry.api.stringpattern.PatternRepository - This class will register a Perl-style regular expression or a specific string with the systems pattern repository. When a match is found the ApplicationMenuItem(s) associated with the pattern will appear in the current application's menu.
net.rim.blackberry.api.menuitem.ApplicationMenuItem- The ApplicationMenuItem includes the action that will occur once a match is found and is invoked by the BlackBerry smartphone user.
The application is once again configured as an auto-start system module. This is done to register the regular expression and menu item with the systems pattern repository upon system start up.