Advanced Cellphone Programs in BREW

In the previous two parts of the series, we have covered

how to set up the BREW environment, write basic applications and test them on

the cellphone. This time we will cover more advanced topics, and see how to draw

graphics, use sounds and set up timers and such for applications that require

it.

Setting up the basic code



The first thing that we need to do before we start writing the code for

drawing the graphics is to set up the application structure. This is needed

because, for example, all drawing functions in BREW will require a pointer to

the display device. This pointer, and several others are included in the

application structure and put in a header file, usually to be initialized on the

start of the application and destroyed when the application closes.

Here is the code for the header file that we will use for

our brew3 project:

// brew3.h



/* Application structure */







typedef struct _CIbrew3  {







            AEEApplet
a;







            AEEDeviceInfo
m_deviceInfo;







            IGraphics*
m_pIGraphics;



} CIbrew3;

This is a small header file, but will serve our purpose

well for now. Remember that for complex applications, you will mostly end up

keeping persistent data in this structure as well. Below is the code for brew3.c

that contains all our actual functions.

/* FILE: brew3.c */







#include "AEEModGen.h"
// Module interface definitions







#include "AEEAppGen.h"
// Applet interface definitions







#include "AEEShell.h"
// Shell interface definitions







#include "AEEStdLib.h"
// Standard libray







#include "AEEGraphics.h"
// Graphics interface definitions







#include "brew3.bid"     // Binary class id







#include "brew3.h"

static boolean

brew3_HandleEvent(IApplet * pi, AEEEvent eCode, uint16 wParam, uint32 dwParam);







static boolean brew3_InitObjects(CIbrew3* pApp);







static void brew3_CleanObjects(CIbrew3* pApp);







static void brew3_DrawScreen(CIbrew3* pApp);

int

AEEClsCreateInstance(AEECLSID ClsId,IShell * pIShell,IModule * po,void ** ppObj)







{







   *ppObj = NULL;







   if(ClsId == AEECLSID_BREW3){







      if(AEEApplet_New(sizeof(CIbrew3), ClsId,
pIShell,po,(IApplet**)ppObj, (AEEHANDLER)brew3_HandleEvent,



(PFNFREEAPPDATA)brew3_CleanObjects)  == TRUE)

return(AEE_SUCCESS);







   }







            return (EFAILED);







}

static boolean

brew3_HandleEvent(IApplet * pi, AEEEvent eCode, uint16 wParam, uint32 dwParam)



{ 







            CIbrew3* pApp
= NULL;  // Applet pointer







            pApp =
(CIbrew3*)pi;







            if (pApp ==
NULL)

return FALSE;







            switch (eCode)








            {







      case EVT_APP_START:

if (!brew3_InitObjects(pApp))

return FALSE;

brew3_DrawScreen(pApp);

return(TRUE);







      case EVT_APP_STOP:

return TRUE;



      default:

break;







   }







   return FALSE;







}

static boolean

brew3_InitObjects(CIbrew3* pApp) {







            int nRet=0;

// Create graphics object







            nRet =
ISHELL_CreateInstance(pApp->a.m_pIShell, AEECLSID_GRAPHICS, (void **)&pApp->m_pIGraphics);







            if (nRet !=
SUCCESS)

return FALSE;

// Get device info

ISHELL_GetDeviceInfo(pApp->a.m_pIShell,

&pApp->m_deviceInfo);







            return TRUE;







}

static void

brew3_CleanObjects(CIbrew3* pApp) {







            // Release
graphics object







            if (pApp->m_pIGraphics
!= NULL) {

IGRAPHICS_Release(pApp->m_pIGraphics);

pApp->m_pIGraphics = NULL;







            }







}

static void

brew3_DrawScreen(CIbrew3* pApp) {







            AEERect Rect;

IDISPLAY_ClearScreen(pApp->a.m_pIDisplay);







            Rect.x = 5;







            Rect.y = 5;







            Rect.dx =
pApp->m_deviceInfo.cxScreen - 10;







            Rect.dy =
pApp->m_deviceInfo.cyScreen - 10;

IDISPLAY_DrawRect(pApp->a.m_pIDisplay, &Rect,

MAKE_RGB(0,0,255), 0, IDF_RECT_FRAME);

IDISPLAY_Update(pApp->a.m_pIDisplay);







}

Long as it is, all it does is draw a blue border along the

border of the screen of the cellphone. Most of the code that we have put here is

necessary for the functioning of the simplest of applications, and you can build

functionality on top of this quite easily. If you trace the code, you will see

that it is the 'brew3_DrawScreen()' function that is doing the drawing. To

make our program draw other objects, we only need to modify this code. We have

initialized the pointer to the graphics interface, but haven't used it. The

rectangle function we have used does not need it, but many other graphics

functions require it. Following is a list of useful graphics functions.

IGRAPHICS_SetBackground: Sets the screen background

color



IGRAPHICS_SetClip: Sets the clipping rectangle. Any graphic updates
outside this rectangle do not take effect.







IGRAPHICS_StretchBlt: Draws an image by stretching it to fit a rectangle







IDISPLAY_BitBlt: Same as IGRAPHICS_StretchBlt, but with no stretching,
but faster



IDISPLAY_ClearScreen: Clears the screen


IDISPLAY_Update: Updates the screen after a graphics call. 


Otherwise there is big a chance that the screen will remain in its previous
state



IDISPLAY_FillRect: Fills a rectangle with color

Setting up timers



Threads do not exist in BREW. This is faked using timers. Timers set up a time
delay after which a function is automatically called. For instance, consider

that you have a ball bouncing around the screen and a score running of how many

bounces it has had.  After drawing the screen, you would call the function

that updates the ball position after a short delay by setting up a timer, and

meanwhile update the score if necessary. The function used to set timers is 'ISHELL_SetTimer'.

As arguments, it will take a pointer to the shell, the time delay in

milliseconds, name of the function to call, and the data that needs to be passed

to the function. 'ISHELL_CancelTimer' can be used to cancel any or all

timers in an application.

Using sound



Sound plays an important role in games and applications on cellphones. The

sound interface is also used for vibration, but that is something which is

ill-advised, since most BREW implementations of vibration differ from each other

and is difficult to standardize for. To play sounds, use the

'ISOUNDPLAYER_SetInfo' function to set the source and other settings. You

need to register a callback function (which periodically gets the status of

sound playback) using “ISOUNDPLAYER_RegisterNotify' and then actually play

using 'ISOUNDPLAYER_Play'.

Anuj Jain