Part I - Preliminaries
If you wish to perform the steps outlined in this article, you require the following items:
- Microsoft Visual C++ 6.0® or better, and
- Version 1.1 of the BREW SDK.
To view the minimum system requirements and obtain specific, SDK installation instructions, view the SDK 1.1 readme file. Note that I assume you have read What is BREW?, the previous article in this series.
Throughout this example, you need to know that file naming is important. Specifically, the application's module information file (.mif) must have the same name (i.e. prefix) as its .dll. In essense, with BREW you need to pick a name and stick with it! The significance of the .mif file suffix will become apparent as you read through this article. The next article will delve deeply into the creation of the .dll that runs on the BREW Emulator™.
BREW Application Wizard
Version 1.1 of the SDK includes a BREW Application Wizard™ that is not available in the version 1.0 release. This application wizard sets most of the applicable project options and produces the minimal skeleton code for a BREW Application, assuming you intend to do your development in C. The project settings and starter code are SDK 1.0 compliant. In the US, there are currently 4 BREW phones available: 2 equipped with version 1.0 of the BREW Application Execution Environment (AEE) and 2 with version 1.1. To ensure compatibility with all these phones, and those yet to be released, you will likely want to use version 1.0 of the SDK for development projects that you intend to commercialize. Should you decide on this course of action, you can use SDK 1.1 to generate your base project, then copy your application-specific files to a safe place, uninstall version 1.1 and download and install version 1.0 of the SDK for the remainder of your development. In this way, you can ensure that your application is version 1.0 compliant and therefore capable of running on current and future phones.
Once you have installed the SDK, open Visual C++ and click File > New. The New dialog should open with the Projects tab selected. As shown in Figure 1, select BREW Application Wizard, ensure that the path to \yourBREWdir\Examples is entered in the Location textbox, then enter "helloBREW" as the Project Name. Click OK to start the BREW Application Wizard. This should bring up the dialog pictured in Figure 2. For the simple application currently under construction, We don't need support for any of the items identified in this dialog. Thus, we can leave all of the checkboxes blank. Had we needed support for any of these items, it is important to realize that merely selecting the corresponding checkboxes in this dialog may not be sufficient. All that these checkboxes do is ensure that the proper interface header files are included in the source file generated by the wizard. The application must have the corresponding privilege level specified on the General tab of the BREW MIF Editor™. The MIF Editor is discussed below and a screenshot of its default view is given in Figure 4. We'll discuss these privilege levels in detail when we cover the related interfaces in later articles. For now, click Next to proceed to the next step in the Application Wizard.
The MIF Editor
In step 2 of the wizard, a note reminds us that we need to create a Module Information File (.mif) for our BREW application. Click the button provided by the wizard to start the BREW MIF Editor.
On the Applets tab of the MIF Editor's main dialog, click the New Applet button to bring up the ClassID Generation dialog shown in Figure 3 (the terms applet and application are used interchangeably throughout this article). Note that the class ID must be unique. A quick perusal of the header files "AEEClassIDs.h", "AEEUsageAppIDs.h", and "AEESampleAppIDs.h" in the \yourBREWdir\inc\ directory shows that 0x1234ABCD does not conflict with any of the IDs included with the SDK. For a commercial application, we would need to obtain a globally unique ID from the BREW Developer Extranet™. For now, select Locally and type 1234ABCD, or any other non-conflicting ID, in the ClassID textbox. Click the Generate button and click Yes in response to the Are you sure you want to generate a ClassID locally? prompt.
In response to the Generate command, the MIF Editor creates a BREW ID (.bid) file. This file simply contains a #define for the class ID generated locally within the MIF Editor. In the next article, we'll ensure that "helloBREW.bid" is #included in the "helloBREW.c" source file. Figure 4 shows the Applets tab of the BREW MIF Editor. Except for the fact that we have not yet supplied a file for the Icon, your MIF Editor instance should appear as in Figure 4. Leave the MIF Editor open; we'll come back to it shortly.
Three bitmaps need to be included in the .mif file: one approximately 85 x 40 pixels, one 26 x 26 pixels, and a thumbnail image 16 x 16 pixels. You can create these bitmaps (.bmp) at any time using Microsoft Paint™ or the resource editor within Visual Studio®. Figure 5 shows the 85x40 pixel image I created using the latter tool. Obviously, you can use whatever images you please.
Once you've finished the 3 bitmaps, save them and return to the MIF Editor where you can specify your 26x26 pixel image as the Icon. Next, click the Advanced button on the MIF Editor's Applets tab. The dialog displayed provides spaces to specify an Image and a Thumbnail Image. The Image is your 85x40 pixel bitmap and the Thumbnail Image is your 16x16 pixel bitmap. This example is intended for the Sharp Z800 phone which has a 128x144 pixel display and a maximum Image size of 108x72 pixels. Note that this maximum size applies only in this MIF Editor context. The dimensions of images based on the SDK's IImage interface are governed only by the device's physical screen size. Be aware that screen size and maximum Image dimensions vary from phone to phone. Detailed phone specifications are available to authenticated BREW developers via the BREW extranet. To gain an understanding of what is required to become an authenticated BREW developer, see the Qualcomm® BREW website.
As an aside, you can create large images that end up displaying as animations on both the emulator and the phone. In this MIF Editor context, this is accomplished by simply creating a single bitmap consisting of several, horizontally arranged, identically-sized frames. Thus the total width of the bitmap can be greater than the device's display width, with the understanding that only one frame of the animation will be displayed at any given time. Note that, in order for this to work, the bitmap's width must be an exact multiple of its height.
Now that we've created a basic module information file, we can close the MIF Editor and continue our exploration. Remember that it is essential for the .mif to have the same name (prefix) as the application's .dll. Note that the "helloBREW.mif" file just created must be copied to the ...\yourBREWdir\Examples\MIF\256Color\ directory in order for the AEE to find it and properly initialize the helloBREW application. This will become especially important next time, when we add our own source code to that generated by the BREW AppWizard and get the application running on the BREW Emulator™.
The Resource Editor
Most applications require string and image resouces, not to mention some kind of user interface consisting of various screens. The BREW Applet Resource (.bar) file serves as your application's central repository for such items. Later in this series, we will work with image and user interface resources. For this introductory application, all we need is a simple resource file that contains two strings that we'll load and display at runtime. Start the Resource Editor by clicking the shortcut installed in your BREW program group. Figure 6 shows how the resource editor looks after the 2 strings have been entered. Initially the right pane of this dialog is empty.
To familiarize yourself with all the ins and outs of the resource editor, read the corresponding guide included with the SDK documentation. For now, right click in the left pane and select New String..., or simply use the keyboard shortcut, ALT-S. The dialog shown in Figure 7 is displayed. Use Figure 6 to fill in the contents of this dialog box for each of the required strings. Once the strings have been entered save the BREW Resource Intermediate (.bri) file as "helloBREW.bri" by selecting File > Save or clicking on the diskette icon on the tool bar. Note that you open the .bri file in the resource editor to make any changes. Whenever you create or edit an application's resources, you must click the blue 'Q' icon on the tool bar after you are done. Doing so creates two files: "helloBREW.bar" and "helloBREW_res.h".
You must copy the "helloBREW_res.h" file to the ...\yourBREWdir\examples\helloBREW\ directory and #include it in "helloBREW.c". The "helloBREW.bar" file needs to be copied to the ...\yourBREWdir\Examples\en\256Color\ directory. As it runs on the emulator, the helloBREW application will access the string resources from "helloBREW.bar" on an "as required" basis. On a phone, at least in most non-trivial cases, an application will never need simultaneous access to all of its resources. Thus bulky strings, images, and UI elements can be relegated to the the phone's embedded file system (EFS) instead of consuming precious RAM. Additionally, the resource file concept eases the process of application internationalization.
In this article, three important BREW SDK tools have been introduced: the BREW Application Wizard, the BREW MIF Editor, and the BREW Resource Editor. The BREW Application Wizard created a skeletal BREW project that can be used as a baseline for our BREW application. The BREW MIF Editor created a module information file (.mif) that contains essential information such as our application's unique class ID, its category, and the images associated with each of the 3 icons required by most applications. The BREW Resource Editor was used to create our application's resources. These resources were then compiled into a BREW Applet Resource (.bar) file that serves up resources whenever the application requests them. Next time, we will disect the "helloBREW.c" source file as generated by the application wizard, add our own code to flesh out the application's simple functionality, and run the application using the BREW Emulator™. Also, we'll see how to debug a BREW application using the Visual C++ debugger and the BREW Emulator.
© Copyright 2002, Golden Creek Software Inc.