Categories: BREW | Getting Started Guide

This page was last modified 23:25, 3 July 2008.

From Forum Nokia Wiki

Overview of the BREW development process

This section starts by offering a high-level view of the process of creating a BREWapplication,
then examines each element more closely.
The BREW SDK is made up of several components, including the following:
• BREWApplication Execution Environment (AEE) provides the foundation for BREW
applications
• A set of tools that are the main development elements of the SDK (MIF Editor,
Resource Editor, Emulator, and Device Configurator)
• BREW header files
• BREW utilities for adding functionality to your BREW applications
- PureVoice Converter (New in BREW 1.1)
- 2BitTool (New in BREW 2.0)
- NMEA Logger (New in BREW 2.0)

• Add-ins to Microsoft Visual Studio to ease your application development
- BREW Application Wizard add-in (New in BREW 1.1)
- Automated ARM compiling add-in (New in BREW 1.1)
- BREW Integrated Help add-in (New in BREW 2.0)
• Sample applications to demonstrate BREW capabilities
• Online help (New in BREW 2.0)

The process works like this:
(1) With your plan for the next killer application in mind, use the BREW Application Wizard, an add-in to Microsoft Visual Studio, to create the project file, workspace file, a skeletal source file, and two additional files (AEEAppGen.c and
AEEModGen.c) that are essential to all BREW applications.

(2) Create a Module Information File (MIF) that includes all module- and appletspecific information required to load the applet.
(3) Create resources, such as strings, images, dialogs, and controls, to be used by the application.
(4)  Compile the source files generated by the BREW Application Wizard and the resource files to create the application DLL file.
(5) Launch the BREW Emulator, specifying the MIF and Applet directories, and test your application.

Creating your project in Visual Studio
The BREWApplicationWizard guides you through the tasks involved in creating a new BREW
application project, including the creation of the following files:
• Project file (myfirstapp.dsp)
• Workspace file (myfirstapp.dsw)
• Application source file (myfirstapp.c)

Two other files required by BREW applications, AEEAppGen.c and AEEModGen.c, are
included with the BREW SDK in the <BREW/Src> directory. These two files are automatically
included in your new BREW project when you use the BREW Application Wizard.

Writing your BREW application
After creating your Visual Studio project and the skeletal application source file (myfirstapp.c),
you can begin coding your first BREW application.

The MIF
If you were to immediately compile the application, you would receive one compilation warning
and one error. These occur because all BREW applications require a MIF file containing
unique BREW ClassIDs (BID) for each of the module’s classes. After you create the MIF, the
warning and error are removed.
These are the steps required to create a MIF for a BREW module called myfirstapp:
(1) From the BREW Developer Extranet, obtain a BID file for each class and applet
that the module contains. Each BID file contains a unique, 32-bit ClassID that is
stored in the MIF.
(2) Compile and link the BID and application source files to create the application’s
DLL file (myfirstapp.dll).
(3) In the MIF Editor, enter the required information, including the ClassIDs contained
in the BID file(s), and save the MIF asmyfirstapp.mif.
The MIF and DLL are used to test the application in the Emulator.

Resources
As you write MyFirstApp, you will also need to create resource files that contains character
strings, images, and dialogs that are loaded at runtime. Resources are useful for storing
language-specific strings, dialogs, and bitmaps. If you need to localize your application for use
in a target device in a different language, you simply need to translate the resources in the
resource file. It is not necessary to recompile the MOD or DLL file. So rather than hard coding
controls into your application source code, consider using resources whenever possible.

These are the steps required to create resource files for a BREW module:
(1) Use the Resource Editor to create all character strings, images, and dialogs to be used in your application. The Resource Editor creates a BREW Resource Intermediate (BRI) file that contains all of the resource ID information for the
application. As you create resources, you assign each a unique resource ID number.
(2) The BRI file is then compiled by the Resource Compiler to produce the BREW Applet Resource (BAR) file and a resource header file, with the _res.h extension. The BAR file is used by the BREW executable file (MOD or DLL) at runtime to load
resources.

(3)  When you compile your C source code, include the header file (myfirstapp_res.h)
so that it is compiled and linked along with the other application source files to
produce the DLL file.

Testing your application on the Emulator
After you have created a DLL and a MIF (and optionally, resource files) for your application, you can run it on the Emulator. The Emulator presents an image of a selected handset and  emulates the running of your application as it will appear on the actual handset. You can load your application in the Emulator by specifying the applet directory that contains
the DLL. By default, the MIF directory is the same as the applet directory. When you run the Emulator, the BREW Application manager presents a series of applets contained in the applet directory. When you choose your application from the list, the Emulator executes the application’s DLL, showing its initial screen on the device. If the application uses resources, it
uses the resource-loading functions in the IShell interface to load the resources from the application’s BAR file.

Before you begin
Before attempting to build your first BREW application, complete the following steps.
• Obtain Microsoft Visual Studio 6.0. Visual Studio.NET is not yet supported.
• Download and install the latest version of the BREW SDK. Here is the download site: https://brewx.qualcomm.com/developer/sdk/download.jsp.

Your objective for MyFirstApp
For your first taste of BREW, you will create a simple application, called MyFirstApp, that performs the following functions:
• It loads two text strings from a resource file that you define.
• It prints the strings in the upper half of the device screen.
• It draws a thin, color-filled, horizontal rectangle, dividing the screen into two halves.
• It loads a bitmap image, representing a cursor, from the resource file and draws the cursor in the middle of the bottom half of the screen.
• It allows the user to move the cursor bitmap using the up, down, left, and right arrow keys on the device.

Creating the MyFirstApp project files
The following instructions are designed to lead you through the creation of MyFirstApp. The
tutorial begins with the BREW Application Wizard (New in BREW 1.1), describes the MIF
Editor and Resource Editor, discusses the functions you need to define to meet the objectives
stated above, and explains how you can compile and test the application. For more detailed
instructions on using the BREW Application Wizard, or any of the other BREW SDK tools, see
BREW documentation on page 6 for the list of documentation included with the BREW SDK.
To create the MyFirstApp project with the Application Wizard
1. Start Microsoft Visual Studio, and choose File > New.
The New dialog box opens.
2. Click the Projects tab.

3. Select BREW Application Wizard and do the following:
a. In Project name, type MyFirstApp.
b. In Location, enter a path to the directory where you want to store the files for the project.
c. Click OK.
The first of two BREW Application Wizard windows opens.
This window allows you to define the types of interfaces you intend to use in your
application.
4. Leave all of the check boxes unchecked, and click Next.
The second BREW Application Wizard window opens.

At this point, the experienced BREW developer has two options:
• Bypass the MIF Editor and complete the BREW Application Wizard to build the
BREW application project file, leaving the creation of the MIF for a later time.
• Create the MIF now.
You have the option of skipping the MIF creation process now, but because the MIF is essential to all BREW applications, it is recommended that you create it before completing the BREWApplicationWizard. .
5. Click MIF Editor.
The BREW MIF Editor window opens.

6. Click New Applet.
The ClassID Generation dialog box opens.

7. Make the entries shown above.
NOTE: The name you assign the ClassID should be the same name you assigned
the project in the BREW Application Wizard.

NOTE: The Locally option allows you to run your application for testing purposes.
Before you can submit an application for TRUE BREW™Testing, you are required
to obtain a unique, 32-bit BID for each BREW class you create, including BREW
system classes and all applet and non-applet classes, from the BREW Developer
Extranet. For more information, see the BREW MIF Editor Guide.
8. Click Generate.
A confirmation box asks if you are sure you want to generate the ClassID locally.
9. Click Yes.
The Save As dialog box opens, prompting you to specify a location for the
myfirstapp.bid file.
10. Navigate to the <BREW/Examples/MyFirstApp> directory and click Save.
The ClassID you defined is added to the main MIF Editor window,

11. In Name, type MyFirstApp. This name appears on the device display when the
user chooses the applet from the device’s applet menu.
NOTE: You must always ensure that the MIF filename is not made up exclusively
of numbers, such as 1003.mif. The name of the MIF must contain, and must begin
with, alphabetical characters. Examples of valid MIF names are helloworld.mif,
b2b.mif, and good4u.mif.
12. In the Applet Type combo box, select Tools.
NOTE: Applets can be grouped by applet type on the device’s applet menu and on
the carrier web site from which the user downloads applications for purchase. The
supported applet types are Game, Tools, PIM, Web Applet, and Hidden. Hidden
applets do not appear in the Application Manager on the device. They are activated
when certain circumstances occur. A screen saver, for example, is a hidden applet.
It is activated only after a predefined amount of inactivity occurs.
NOTE: For the purposes of MyFirstApp, leave the Icon field blank. This field allows
you to specify the path and filename for a medium-sized graphic image
(approximately 26x26 pixels) you want to use in the MIF.When you leave the field
blank, a default image is supplied by BREW.
13. For MyFirstApp, it is not necessary to enter information on any of the other MIF
Editor tabs. Choose File > Save As, assign the MIF the myfirstapp filename, and
click Save.

The Save As dialog box closes.
14. In the MIF Editor window, click the Windows Close button.
15. In the BREW Application Wizard window, click Finish.
The New Project Information dialog box opens.

16. Click OK.
The Microsoft Visual C++ window reopens with your new BREWapplication project
loaded in the workspace.

The Application Wizard has created the following files:
• Project file (myfirstapp.dsp)
• Workspace file (myfirstapp.dsw)
• Application source file (myfirstapp.c)
NOTE: Two other files required by BREW applications, AEEAppGen.c and
AEEModGen.c, are included with the BREW SDK in the BREW/Src directory.
These two files are automatically included in your new BREW project.
17. Look over the source code for MyFirstApp and familiarize yourself with the
information that was automatically generated by the BREW Application Wizard.
18.When you’re ready to move on, proceed to Creating resources for MyFirstApp

Initial source code for myfirstapp.c
When you have run the BREW Application Wizard, your source code looks like the following.
/*=========================================================================
FILE: myfirstapp.c
=========================================================================*/
/*=========================================================================
INCLUDES AND VARIABLE DEFINITIONS
======================================================================== */

1. include "AEEModGen.h"// Module interface definitions
   #include "AEEAppGen.h"// Applet interface definitions
   #include "AEEShell.h"// Shell interface definitions
   /*-------------------------------------------------------------------
   Function Prototypes
   -------------------------------------------------------------------*/
   static boolean MyFirstApp_HandleEvent(IApplet * pi, AEEEvent eCode,
   uint16 wParam, uint32 dwParam);
   /*=========================================================================
   FUNCTION DEFINITIONS
   ======================================================================== */
   /*========================================================================
   FUNCTION: AEEClsCreateInstance
   DESCRIPTION
   This function is invoked while the app is being loaded. All Modules must
   provide this function. Ensure to retain the same name and parameters for
   this function. In here, the module must verify the ClassID and then invoke
   the AEEApplet_New() function that has been provided in AEEAppGen.c.

=============================================================*/

int AEEClsCreateInstance(AEECLSID ClsId,IShell * pIShell,IModule * po,void
** ppObj)
{
*ppObj = NULL;
if(ClsId == AEECLSID_MYFIRSTAPP){
if(AEEApplet_New(sizeof(AEEApplet),ClsId,pIShell,po,(IApplet**)
ppObj,(AEEHANDLER)MyFirstApp_HandleEvent,NULL)
== TRUE)
{
// Add your code here .....
return (AEE_SUCCESS);
}
}
return (EFAILED);
}

/*=========================================================================
FUNCTION MyFirstApp_HandleEvent
DESCRIPTION
This is the EventHandler for this app. All events to this app are handled
in this function. All APPs must supply an Event Handler.
PROTOTYPE:
boolean MyFirstApp_HandleEvent(IApplet * pi, AEEEvent eCode, uint16
wParam, uint32 dwParam)

===============================================*/

static boolean MyFirstApp_HandleEvent(IApplet * pi, AEEEvent eCode, uint16
wParam, uint32 dwParam)
{
switch (eCode)
{
case EVT_APP_START:
// Add your code here .....
return(TRUE);
case EVT_APP_STOP:
// Add your code here .....
return TRUE;
default:
break;
}
return FALSE;
}

Creating resources for MyFirstApp
One of the objectives for the creation of MyFirstApp  is to create a resource file that contains two text strings and a cursor image. You won’t always know up front all of the resources that a given application requires. In general, you will define the resources you know about in the BRI file and, using the Resource Editor Compiler, compile them into the BAR file
that is used at runtime by the application DLL whenever resources are required. Then, as you define more controls for the application, you can add them to the BRI and compile when necessary.

To define the string resources for MyFirstApp
1. Choose Start > Programs > BREW > BREW Resource Editor.
The BREW Resource Editor window opens.

2. Choose Resource > New String.
NOTE: You can also right-click on String in either of the window panes, and choose
New String.
The String Resource dialog box opens. 

3. Make the entries shown above.

A Resource ID number between 1 and 5000 is assigned automatically; however,
you can change it if you want to assign a specific ID. The important thing to remember is that the ID must be a unique integer among string resources within  the same resource file (BRI). So you can assign Resource ID 1 to two string
controls as long as you do not use them in the same BRI file. The Value field contains the actual string content for the resource.

4. Repeat steps 2 and 3 to add your second string, making the entries shown below.

5. Click OK.
The String Resource dialog box closes, and the string resources you created appear in the right pane of the BREW Resource Editor window.

6 .Now you’re ready to create your image resource.
To define the image resource for MyFirstApp
 1. With the Resource Editor window open, choose Resource > New Image.
 NOTE: You can also right-click on Image, and choose New Image.

2. Make the entries shown above.
NOTE: For the Image Path, click Browse, navigate to <BREW\Bitmaps> and load
cursor-1.bmp.
3. Click OK.
The Image Resource dialog box closes, and the image resource you created
appears in the right pane of the BREW Resource Editor window.

4. Click File > Save As.
5. In the Save As dialog box, navigate to <BREW\Examples\MyFirstApp> and save the file as myfirstapp.bri.
6. You are now ready to compile your BAR file.

To compile the BREW resource file
''''1. In the BREW Resource Editor window, choose Build > Build QUALCOMM .BAR/.H files.

A message box opens informing you that the resource (BAR) file and header
(res_h) file have been created. They are stored in the same directory as the BRI file.
2. If you had not previously saved the intermediate files, the Save As dialog box would have opened, where you would have indicated where you wanted the BRI stored and so on.
3. You are now ready to create functions in the MyFirstApp source code.

'

Writing the source code for MyFirstApp

Now you have created your base project, created a MIF, and defined resources in a BAR file, you are ready to start writing the actual source code for MyFirstApp.

Given the skeletal source code provided by the BREWApplication Wizard 

as a starting point, you will make the following additions and modifications to the
base code:
• #include lines must be added in the header to accommodate additional interface
definitions needed by MyFirstApp.
• Application-specific data structure must be defined.
• New function prototypes must be defined for the InitAppData, FreeAppData, and Move functions.
• AEEClsCreateInstance must be modified. This function is created by the BREW
Application Wizard; however, you need to make some minor modifications to it.
• A function for initializing the application-specific data must be defined.
• A function for freeing application-specific data must be defined.
• An event handler must be modified for MyFirstApp.
• A helper function must be defined to facilitate movement of the cursor on the device screen.

Adding #include statements
''''When you ran the BREWApplicationWizard, it automatically generated the following #include statements in your source code:
/*=========================================================================
INCLUDES AND VARIABLE DEFINITIONS
======================================================================== */
#include "AEEModGen.h" // Module interface definitions
#include "AEEAppGen.h" // Applet interface definitions
#include "AEEShell.h" // Shell interface definitions
As you can tell by looking at the comment lines, these three elements provide definitions for
the IModule, IApplet, and IShell BREW interfaces. These three interfaces are used in all
When you are creating a BREW application, however, you will need to add other #include
statements to handle the other BREWinterfaces required by the application. You also need to
add definitions for any global constants needed by the application.
To add #include lines
1. Start Microsoft Visual Studio and load the MyFirstApp workspace (myfirstapp.dsw).
2. Click the FileView tab and open myfirstapp.c in the workspace.
3. Scroll down to the INCLUDES AND VARIABLE DEFINITIONS section shown
above, and add the following #include lines after the AEEShell.h line.
#include "myfirstapp_res.h" // Resource ID definitions
#include "myfirstapp.bid" // Applet ClassID

4. Save your work and proceed to the next procedure.
Adding the application-specific data structure
The application-specific data structure defines the structure used to store data that needs to
be remembered throughout the life of MyFirstApp. The most important thing to remember
when setting up this structure for BREW applications is that the first data member must always
be an instance of type AEEApplet. This structure exposes the most commonly-used BREW
interface pointers, such as Shell, Module, and Display.

To add the application-specific data structure
1. Scroll down in your source code, and insert a blank line between the Includes and
Variable Definitions and the Function Prototypes section.
2. Type the following lines:
typedef struct _CMyFirstApp
{
AEEApplet a; // Mandatory first AEEApplet data member
int m_cxWidth; // Stores the device screen width
int m_cyHeight; // Stores the device screen height
int m_nCursorX; // Stores the cursor bitmap x coordinate
int m_nCursorY; // Stores the cursor bitmap y coordinate
IImage * m_pIImage;// IImage interface pointer
}CMyFirstApp;
NOTE: As you can see, this typedef meets the requirement that the AEEApplet
data member is first. This requirement is related to an applet being dynamically
downloaded.
3. Save your work and proceed to the next procedure.

Tutorial: Creating Your First BREW Application
Adding function prototypes
When you ran the BREW Application Wizard, it automatically generated the following function
prototype for the event handler:
static boolean MyFirstApp_HandleEvent(IApplet * pi, AEEEvent eCode, uint16
wParam, uint32 dwParam);
For MyFirstApp, you must add three new functional protoypes to support functions you will be
adding to the code.
To add function prototypes to MyFirstApp
1. Scroll down in your source code, and type the following after the event handler
functional prototype:
static boolean MyFirstApp_InitAppData(IApplet* pMe);
static void MyFirstApp_FreeAppData(IApplet* pMe);
static void CMyFirstApp_Move(CMyFirstApp * pMe, int xc, int yc);
2. Save your work and proceed to the next procedure.
Modifying the AEEClsCreateInstance function
The purpose of the AEEClsCreateInstance() function is to create an instance of the AEEApplet
data structure for each applet or class supported by the module. The AEEApplet data structure
is created by invoking the AEEApplet_New() function with the address of the applet specific
handle event function.
The BREW Application Wizard provided you with the underlying structure of the
AEEClsCreateInstance() function, with commented placeholders for you to type your
application-specific code. The code is shown below.
int AEEClsCreateInstance(AEECLSID ClsId,IShell * pIShell,IModule * po,void
** ppObj)
{
*ppObj = NULL;
if(ClsId == AEECLSID_MYFIRSTAPP){
if(AEEApplet_New(sizeof(AEEApplet),ClsId,pIShell,po,(IApplet**)
ppObj,(AEEHANDLER)MyFirstApp_HandleEvent,NULL)
== TRUE)
{
// Add your code here .....
return (AEE_SUCCESS);

}
}
return (EFAILED);

To modify AEEClsCreateInstance for MyFirstApp
1. At , make the following two changes:
a. Change the sizeof parameter in the AEEApplet_New function from AEEApplet
to CMyFirstApp.
b. In the nested IF statement , replace NULL with the following:
((PFNFREEAPPDATA)MyFirstApp_FreeAppData)
This function frees the application data. It is registered with the applet
framework when the applet is created (inside the AEEClsCreateInstance
function), and is called by the application framework when the reference count
of the applet reaches zero. This function must free all the application’s allocated
data. For example, if the application stored data when it was suspended and
resumed, that data must be freed.
2. Replace the comment line with the following line:
if(MyFirstApp_InitAppData((IApplet*)*ppObj) == TRUE)
This statement calls the MyFirstApp_InitAppData function which initializes all applet-specific data after the applet has loaded successfully.

3. Save your work and proceed to the next procedure.

Adding the MyFirstApp_InitAppData function
''''Now that you have successfully set up AEEClsCreateInstance, it’s time to set up the InitAppData function which is used to initialize applet-specific data.

To add the MyFirstApp_InitAppData function
1. Scroll down to the end of the code for the AEEClsCreateInstance function and
insert a blank line.
2. Type the following code:
static boolean MyFirstApp_InitAppData(IApplet* pi)
{
AEEDeviceInfo di;
CMyFirstApp * pMe = (CMyFirstApp*)pi;
pMe->m_pIImage = NULL;
if ((pMe->m_pIImage = ISHELL_LoadResImage(pMe->a.m_pIShell,
MYFIRSTAPP_RES_FILE,IDB_CURSOR)) == NULL)
return FALSE;
ISHELL_GetDeviceInfo(pMe->a.m_pIShell,&di);
pMe->m_cxWidth = di.cxScreen;
pMe->m_cyHeight = di.cyScreen;
pMe->m_nCursorX = pMe->m_cxWidth/2;
pMe->m_nCursorY = pMe->m_cyHeight*2/3;
return TRUE;
}
3. Take note of the following information:
4. Save your work and proceed to the next procedure.
This statement loads the image from the resource file and stores a pointer to the image in the m_pIImage data member.
This statement uses the ISHELL_GetDeviceInfo function to determine the width and height of the device screen, and stores those values in the applet data structure.
These two lines cache the width and height of the device screen.
These two lines initialize the coordinates of the initial cursor position on the screen. Based on the device screen dimensions, the cursor image is positioned at the halfway point way along the x-axis and 2/3 of the way along the y-axis.

Adding the MyFirstApp_FreeAppData function
Now you are ready to define the FreeAppData function, which frees application data stored in
the applet data structure. This function is registered with the applet framework when the applet
is created using the AEEClsCreateInstance function. It is called by the application framework
when the reference count of the applet reaches zero. At that point, FreeAppData must free all
of the data allocated by the application.
NOTE: Do not call the FreeAppData function directly in your application.

To add the MyFirstApp_FreeAppData function
1. Scroll down to the end of the code for the MyFirstApp_InitAppData function and
insert a blank line.
2. Type the following code:
static void MyFirstApp_FreeAppData(IApplet* pi)
{
CMyFirstApp * pMe = (CMyFirstApp*)pi;
if (pMe->m_pIImage != NULL)
{
IIMAGE_Release (pMe->m_pIImage);
pMe->m_pIImage = NULL;
}
}
3. Save your work and proceed to the next procedure.
Modifying the MyFirstApp_HandleEvent function
Like AEEClsCreateInstance, the BREW Application Wizard provided you with the underlying
structure of the IHandleEvent function, with commented placeholders for you to type your
application-specific code. All BREW applications must have an event handler section. The
code provided by the BREW Application Wizard is shown below.
static boolean MyFirstApp_HandleEvent(IApplet * pi, AEEEvent eCode, uint16
wParam, uint32 dwParam)
switch (eCode)
{
case EVT_APP_START: //Applet start event
// Add your code here .....
return(TRUE);

}

case EVT_APP_STOP:
// Add your code here .....
return TRUE;
default:
break;
}
return FALSE;
}

To modify MyFirstApp_HandleEvent
1. At , insert the following lines:
AEERect rc;
AECHAR szBuf[30] = {0};
CMyFirstApp * pMe = (CMyFirstApp*)pi;
2. At , replace the comment placeholder with the following lines:
case EVT_APP_RESUME:
IDISPLAY_ClearScreen (pMe->a.m_pIDisplay); // Erase whole screen
// Load string "Use arrow keys" from resource file.
ISHELL_LoadResString(pMe->a.m_pIShell, MYFIRSTAPP_RES_FILE,
IDS_STRING1, szBuf, sizeof (szBuf));
IDISPLAY_DrawText(pMe->a.m_pIDisplay, AEE_FONT_NORMAL, szBuf,
-1, pMe->m_cxWidth/5, pMe->m_cyHeight/8, 0, 0);
// Load string "to move cursor" from resource file.
ISHELL_LoadResString(pMe->a.m_pIShell, MYFIRSTAPP_RES_FILE,
IDS_STRING2, szBuf, sizeof (szBuf));
IDISPLAY_DrawText(pMe->a.m_pIDisplay, AEE_FONT_NORMAL, szBuf,
-1, pMe->m_cxWidth/5, pMe->m_cyHeight/5, 0, 0);
// Initialize rectangle
SETAEERECT (&rc, 0, pMe->m_cyHeight/2 - 2, pMe->m_cxWidth, 2);
IDISPLAY_DrawRect (pMe->a.m_pIDisplay, &rc, 0, 1,
IDF_RECT_FILL);
IIMAGE_Draw (pMe->m_pIImage, pMe->m_nCursorX, pMe->m_nCursorY);
IDISPLAY_Update(pMe->a.m_pIDisplay);
3. Take note of the following information:
This function Does this
IDISPLAY_ClearScreen This function erases the device screen.

Tutorial: Creating Your First BREW Application
{
ISHELL_LoadResString This statement occurs twice, each followed by an
IDISPLAY_DrawText function. The LoadResString
functions load the two resource strings from the
application resource file using the IDS_STRING1 and
ID_STRING2 string IDs. The strings are copied to a local
AECHAR type string buffer, szBuf.
IDISPLAY_DrawText The two DrawText functions, each following a
LoadResString function, display the strings stored in the
szBuf buffer at these locations on the screen:
SETAEERECT This function initializes a 2-pixel-wide rectangle object of
IIMAGE_Draw This function displays the cursor in the lower half of the
IDISPLAY_Update This function flushes the text buffers onto the device

4. At , insert the following lines:
case EVT_KEY: // Process key-down event.
switch (wParam)
case AVK_LEFT:
case AVK_RIGHT:
CMyFirstApp_Move(pMe,(wParam == AVK_RIGHT ? 1 : -1),
0); break;
case AVK_UP:
case AVK_DOWN:
CMyFirstApp_Move(pMe,0,(wParam == AVK_UP ? -1 : 1));
break;
• IDS_STRING1 is displayed at the x and y coordinates of screen-width/5 and screen-height/8.
This corresponds to approximately the middle of the top half of the screen.
• IDS_STRING2 is displayed at the x and y coordinates of screen-width/5 and screen-height/5.
This corresponds to the location on the screen directly beneath the first string

39
Handling SUSPEND and RESUME events
It is important to include the EVT_APP_SUSPEND and EVT_APP_RESUME events within
your application’s HandleEvent function so that your application knows how to handle events
that might interrupt its operation. For example, when an SMS message or an incoming phone
call is received, you application needs to know whether it should resume where it left off at the
end of the call or if it should start over.
When BREW suspends an applet, it sends the EVT_APP_SUSPEND event. Depending on
the type of application you are developing, you have a couple of options on how BREWshould
• You can set the applet to return TRUE to the event, indicating that the applet has
processed the Suspend and has not been unloaded from memory. This is how
• You can also have the applet return FALSE to the event, indicating that you do not
want the applet to process the Suspend. When this occurs, BREW sends an
EVT_APP_STOP event and the applet is removed from memory.
When you have finished creating MyFirstApp, you can test EVT_APP_SUSPEND and
EVT_APP_RESUME on the Emulator by clicking Tools > Settings to open the Settings dialog
box. When the dialog box opens, MyFirstApp returns TRUE to Suspend operation. When you
click Cancel to dismiss the dialog box, MyFirstApp issues the EVT_APP_RESUME event and
the cursor in the application remains in the same position you left it.

Adding the CMyFirstApp_Move function
CMyFirstApp_Move is a helper function that allows the user to move the cursor on the device
screen. The function uses an applet data structure pointer and two integer variables
corresponding to incremental movements of the cursor in the x and y directions. For more
information on helper functions, see the BREW API Reference.
To add the CMyFirstApp_Move function
1. Scroll down to the end of the code for the MyFirstApp_IHandleEvent function and
insert a blank line.
2. Type the following code:
static void CMyFirstApp_Move(CMyFirstApp * pMe, int xc, int yc)
{
AEEImageInfo iInfo;
int min, max;
int x = pMe->m_nCursorX;
int y = pMe->m_nCursorY;
IIMAGE_GetInfo (pMe->m_pIImage, &iInfo);
// Erase the previously displayed bitmap from the screen.
IDISPLAY_EraseRgn (pMe->a.m_pIDisplay, x, y, iInfo.cx,
iInfo.cy);
x += xc;
y += yc;
// Delimit the x & y coordinated to lower half of the screen
min = 0;
max = pMe->m_cxWidth - iInfo.cx;
x = ((x < min) ? (min) : (x > max) ? max : (x));
min = pMe->m_cyHeight/2;
max = pMe->m_cyHeight - iInfo.cy;
y = ((y < min) ? (min) : (y > max) ? max : (y));
// Draw cursor at new position.
IIMAGE_Draw (pMe->m_pIImage, x, y);
pMe->m_nCursorX = x; // Store new x coordinate
pMe->m_nCursorY = y; // Store new y coordinate
// Update display.
IDISPLAY_Update(pMe->a.m_pIDisplay);
}

4. Select the device you want to view in the Emulator and click Open.
The Select Device dialog box closes and the selected device image appears in the
Emulator window.
5. Click the right or left arrow key until MyFirstApp is shown.
NOTE: The main image displayed in the screen is missing because you did not
select an image when you created the MIF.
6. Click Select.
7. Click the up, down, left, or right arrow keys to move the cursor around the bottom
half of the screen.
Congratulations, you have successfully created a BREW application!
3. Take note of the following information:
4. Save and your work, and compile the DLL.
NOTE: All you need to know about compiling the DLL is that it must be stored in
the <BREW\Examples\MyFirstApp> directory.
You are now ready to test MyFirstApp on the Emulator.
Testing MyFirstApp on the Emulator
When you have completed all of the steps outlined in this section, it will FINALLY be time for
you to see how your new application works on the Emulator. .
To test MyFirstApp on the Emulator
1. Choose Start > Programs > BREW > BREW Emulator.
The BREW Emulator runs.
2. Make sure that the Applet directory is set to <BREW\Examples>. If needed, choose
File > Change Applet Dir to change the Applet directory.
3. If you want to view MyFirstApp on a different device image than the one currently
displaying, choose File > Load Device.
The Select Device dialog box opens.
In these statements, two local variables (x and y) are initialized with the coordinates
of the current cursor position.
The IIMAGE_GetInfo function gets the image information.
The IDISPLAY_EraseRgn function erases the region on the screen where the cursor
was previously displayed.
This series of lines use algorithms to evaluate if the new cursor coordinates are within
the boundaries of the bottom half of the screen. The IIMAGE_Draw function displays
the cursor at the new coordinates.
This updates the local x and y variables with the new cursor position.