Battery Level and Reception Signal Tutorial

As per request from lithium3r, I've decided to write a short tutorial on how to create battery and signal gauges for flash lite applications. It is especially useful for those deciding to create flash lite menus, as that's one of the things you will usually see on them. We will take a look at creating a very simple battery gauge first.

*NOTE: The FSCommand2 functions shown in this tutorial only work on phones that support the function. Please refer to this for some info on Nokia phones.

Battery Gauge:
The two important commands used to retrieve battery level status are as follows:

status = FSCommand2( "GetBatteryLevel" );
status = FSCommand2( "GetMaxBatteryLevel" );

One function receives the current battery level while the latter retrieves the maximum level (in a numerical form of course). If your phone does not support this function (as in the case of the FL1.1 emulator), it will send back -1.

So what now? With these two values, you're pretty much creating a preloader to a flash movie essentially. First off, you need a movieclip that consists of the bar, with the crosshair being at the left most side of the bar.



Then we proceed with the following two lines which you've seen:

/:currentBattery = FSCommand2( "GetBatteryLevel" );
/:maxBattery = FSCommand2( "GetMaxBatteryLevel" );

Now we'll calculate the fraction that will allow us to adjust the width of our bar accordingly:

/:battFraction = /:currentBattery / /:maxBattery;

This line is just formatting the fraction into percentage form in case you want to display it. In this case, you can create a dynamic textfield with var=battLevel to display the battery in percent form.

/:battLevel = Math.round(/:battFraction*100) add "%";

I've used Math.round() function here, but it seems as though it is not supported in some phones, so a better alternative may be using (int) truncation:

/:battLevel = ((int)(/:battFraction*100)) add "%";

Now we need to decide what the maximum width of the original bar is in order to scale it properly. In this case, I have called the instance to my movieclip 'batt':

/:maxWidth = batt._width;

Using the fraction calculated, multiply it with the maximum width to resolve the current width you will display:

/:currentWidth= /:battFraction * /:maxWidth;

Now we just set the width of the movieclip (batt) to its preferred width using the _xscale command.
**NOTE: batt._width or batt.width are READ ONLY functions in FL1.1:

batt._xscale=/:currentWidth;

There you have it, once you've done this you can take it for a test run. Beware, the FL1.1 emulator will not be able to return battery levels to you, so you will need to test with a real phone! However, I'd recommend predefining values for battFraction just to test out the code to make sure it works.

Reception Signal:
Surprising as it may seem, the two functions responsible to retrieve reception is very similar to what we've seen before:

status= FSCommand2( "GetSignalLevel" );
status= FSCommand2( "GetMaxSignalLevel" );

Like before, we can combine these two values to form a fraction, and then use it to change the width of a bar like the battery. However, from my experience of, reception signals are usually expressed in vertical bars of increasing height, so we will try to recreate this effect.

First off, lets talk about the vertical bars. You will need to decide how many bars in total you want to have. For simplicity sakes, I went with 5. Consequently, I will need 6 frames in my movie clip, one to show each state PLUS one frame for no bars (no reception):

You will need the stop() function on frame one, so that when the movie is placed on stage, it will not zoom through all the frames. Now we need to relate the frame number to the fraction of full signalling. Using this method where each frame increments in bars, we can do the following:

/:currentSig = FSCommand2( "GetSignalLevel" );
/:maxSig = FSCommand2( "GetMaxSignalLevel" );

Now we calculate the fraction of full signal achieved.

/:sigFraction = /:currentSig / /:maxSig;

To calculate the theoretical number of bars we should have, we multiply the fraction calculated by the number of bars we had in our movie clip, which is 5. We perform Math.round because you can not display 3.48 bars, and thus we need to have a rounded number. Again, you can change Math.round() to int() instead, which will hopefully solve any compatiblity issues.

/:numBars = Math.round(/:sigFraction * 5);

This line is extra and used to format the percentage so that it can be displayed in a dynamic text box with var = receptionLevel:

/:receptionLevel = Math.round(/:sigFraction*100) add "%";


Now we call upon the instance of the movie clip that contains the 6 frames (of the bars). I called the instance 'reception'. We tell it to go to the rounded number of bars we calculated. Since frame numbers start at 1, we need to add on 1 to the variable. Recall that frame 1 = no bars, but /:numBars= 0 when there is no reception.

tellTarget("reception"){
gotoAndStop(/:numBars+1);
}

Once again, the emulator will not be able to provide values for the signal, so you will have to test using predefined variables. I hope this little tutorial has provided some insight on how this is done, I present you with a sample screenshot of the finished product: