When I was asked to provide the next installment of the BREW Intro Series, I wrestled with various content ideas. I didn't want to write another "Hello BREW" application, simply because that's already been done to death.
Finally I decided it would be nifty if, over the course of several articles, I could walk my readers through the development of an application with some commercial potential, however modest.
Beyond exploring what it's like to code with the BREW SDK, I thought it would be interesting to chronicle the process of taking a BREW app from concept to commercialization.
Thus once the code has been covered, and all the necessary documentation has been prepared, I'll try to get it through TRUE BREW testing and then see if a carrier will make it available to consumers.
The Big Idea
The application is a simple currency conversion tool. The main screen of the prototype I developed is displayed, with each of its user-interface (UI) elements in focus, in Figure 1.
|Figure 1. The Basic Design|
The UI element at the top of the screen is a simple BREW list menu that the user will employ to select the first of two currencies involved in the transaction she is contemplating. The list menu is almost perfect here because it uses the limited screen real estate sparingly, yet provides the user with multiple options. I say "almost perfect" because some customization is necessary in order to assist the user with navigation. The modifications discussed below hopefully increase the likelihood that the application will pass True BREW Testing. Only time will tell!
As you can see from the first three frames of Figure 1, I've augmented the list menus, and the text control, by adding arrows to help the user find her way around. These visual cues are necessary since the left and right keys are used to move the focus from a list menu, while the up and down direction keys are used to move the focus from the text control or the soft key menu. This shift will undoubtedly lead to some initial confusion. The visual cues are intended to minimize the adverse impact on the user's experience with the application.
As indicated by the graphical depiction of a Windows spinner control, the up and down direction keys are used to select a currency from the list. While the first currency menu has the focus, the user can press the right direction key to move to the Amount: text control, or press the left direction key to move to the soft key menu at the bottom of the screen. The latter is an example of "wrap-around" functionality, incorporated to speed up navigation for the user.
Assuming the right direction key is used to bring the text box into focus, the user can replace, or otherwise update, any existing entry. When the user moves the focus into the text control, our code will automatically position the insertion point at the end of its contents. While the text control has the focus, the phone's "CLR" key can be used to backspace over individual digits (and the decimal point, if present), the '#' key clears all of the contents at once, the phone's numeric keypad is used to enter digits, and the '*' key enters a decimal point. The left and right direction keys can be used to position the text insertion point within the control's contents and the up and down direction keys can be used to move the focus to the upper and lower currency menus, respectively. The value keyed in will represent the amount of one currency involved in the transaction. When the text control has the focus, the little vertical arrows visible at the ends indicate the buttons to use in order to move to another control.
We'll inform the user of these user-interface details in a splash screen, or in a help topic accessible from the soft key menu at the bottom of the screen. We certainly don't have the real estate available to provide this information on the main screen.
Once the user has specified the first currency, and the sum in question, she can, as the arrows indicate, move on to the second currency menu by pressing the down direction key, or return to the first using the up direction key.
Assuming that the user moves on to select the second currency, the screen will appear as shown in the third frame of Figure 1. From this lower list menu, the user can move back up to the text control by pressing the left direction key, or down to the soft key menu at the bottom of the screen by pressing the right direction key.
Let's assume that the user moves down to the soft key menu where, as shown in the prototype, there are two available choices: "Edit Rates" and "Exit". As mentioned earlier, I'll likely add a "Help" selection that the user can choose to obtain directions for using the currency converter (I need to think of a commercial name!). Additional requirements will undoubtedly surface as the application evolves.
The "Edit Rates" button will take the user to a second screen where conversion rates can be updated for each of the tracked currencies. It may be better to simply label this button "Update" and have it present a further menu where the user is given the choice of adding or removing currencies from the menus shown on the main screen or changing exchange rates. An exhaustive list of all the world's currencies will be maintained in a file with the user merely selecting a few that are of interest. After all, if you're an American traveling in Canada, you won't likely need the ability to view an equivalent value expressed in British pounds or Australian dollars.
Imagine an American user is traveling in Canada and comes across some souvenir she would like to purchase. Since the item is priced in Canadian dollars, the user would select "CA Dollar" in the top-most list menu. The user would then move to the "Amount:" text control and enter the price of the item in Canadian dollars. By selecting "US Dollar" from the lower list menu, the static "Equivalent" display area would show the corresponding value in American currency. The conversion is done on the fly (whenever any of the user-interface elements change state) so there is no need for a "Calculate" button. The user could use the "Update" capability discussed above to ensure the store's conversion rate is used in the calculation.
And the Journey Begins...
First of all, I need to point out that I try to be complete and not leave questions hanging when I write. That said, I also don't believe in rehashing topics that are clearly spelled out elsewhere. For example I use Visual Studio 6.0. Many of you may rightly ask "How does it work with .NET?" Similarly, you might be unclear on how to use the 2.x Emulator with applications that must be compiled using the 1.1 header files. The reason that I won't cover this ground in these articles is simple; the answers to these questions, and scores more, can be found here. Also, the searchable Developer Forums and FAQ / Knowledge Base (use the search box in the lower left part of the page) are excellent resources. Last, but not least, the documentation provided with the SDK includes detailed, usually complete, information about using the various API's. So, if I miss something, chances are you'll find what you're looking for in one of these areas. As a postscript on this subject, don't be afraid to look inside the BREW header files that come with the SDK. In some instances, you will find important information that's not included in the SDK documentation.
In my last article, "Intro: Getting Started with BREW," I briefly covered the SDK tools including the MIF Editor, the Resource Editor, the BREW Emulator, and the BREW Application Wizard. In addition to these primary SDK tools, we need to use Visual C++ to produce the .dll that will run on the BREW Emulator, and an ARM compiler to create the module (.mod file) that will run on the targeted device(s). We also need a class ID for the application. We'll use the web-based class ID generator for this purpose. Note that the class ID generator is only accessible to authenticated developers who are able to log in to the Developer Extranet (i.e. you need to have obtained your Verisign authentic document ID). If you haven't acquired access to the extranet, you can use the MIF Editor to manually create a class ID. So you'll have a join the BREW Developer Alliance (this is a good excuse to climb aboard) or else just follow along on your screens.
The following table summarizes the contribution of each of these tools, the files they use and create, and the place each of these files occupies within the overall project.
|Tool ||Purpose ||File(s)|
|MIF Editor ||Stores the application's required information, including its class ID, icons, name, and copyright information. ||Creates a .mif or module information file. This file must be present in the root directory of the device, and in the mif directory specified by the developer in the BREW Emulator. Without the .mif, BREW will act like your application does not exist.|
|Resource Editor ||Serves as a repository for the application's strings, images, and dialog resources. Note that all controls in this application are created manually in code and dialogs are not used. ||The Resource Editor stores all of the entered resources in a BREW Resource Intermediate (.bri) file. The bri is the Resource Editor's native file format.The Resource Editor compiles the resources contained in the .bri into a binary BREW Applet Resource (.bar) file. The application will programmatically load resources from this file as required at run time.The Resource Editor also produces appname_res.h. This file contains #define's for all the resource ID's contained in the .bri file. The developer must include this header in the main application source file so that the resource ID's can be accessed from code.|
|Emulator ||The Emulator serves as the primary test-bed for BREW development. Note that Emulator-based testing is NO SUBSTITUTE for testing on the actual target device. The developer MUST periodically test on the device in order to keep application development on track. ||The Emulator uses the .mif produced by the MIF Editor, the .bar produced by the Resource Editor, and the .dll produced by Visual C++ to simulate BREW applet execution (note that I use the terms "application" and "applet" interchangeably).|
|Application Wizard (Visual C++ 6.0) ||The BREW AppWizard creates a starter project that incorporates skeleton code and basic, Visual C++ project settings for a C-style BREW application. ||The application wizard creates a main .c file for the applet, along with the basic Visual C++ project support files (i.e. .dsw and .dsp, etc.)See my last article for project modifications that must be made in order for the Emulator to function correctly.|
|Class ID Generator ||The class ID generator does just what its name implies. It creates a class ID that is unique for the application. ||The generator produces a BREW ID (app_name.bid) file that must be #included in the main source file in order for the BREW execution environment to match the application with its .mif. If the .bid does not match the class ID specified in the .mif, the application will not load. This error results in the device displaying "Unknown Error (1)" when it tries to load the applet.|
|Visual C++ ||Compiles the application's source code so that the project will run on the BREW Emulator. ||Produces a .dll file that will run on the Emulator to simulate the application executing on an actual device.|
|ARM Compiler ||Compiles the application's source code so that the project will run on a BREW handset. ||Produces a .mod file that will run on the actual device.|
Next time, I'll walk you through the creation of the application's .mif and .bri. Then we'll use the Application Wizard to lay the converter's foundation. We'll also cover the steps necessary to set up the development environment and integrate the BREW Emulator.
Originally published in the BREW Wireless Resource Center