Recipe 22.7. Applying Custom Labels to the Soft Keys

Problem

You want to apply custom labels to the phone's soft keys.

Solution

Use the SetSoftKeys command.

Discussion

In addition to the three- or five-way navigation discussed in the previous section, Flash Lite offers you some level of control over the phone's left and right soft keys. The soft keys are so named because their labels and functionality change depending on the phone's state. For example, a phone might label the left soft key "PHONE BOOK" after starting up, but "EXIT" when displaying the Phone Book.

Relabeling the soft keys is achieved by executing the SetSoftKeys command of fscommand2. fscommand2 is a Flash Litespecific ActionScript function that offers the Flash developer access to many phone-specific data and features at runtime. Among other properties, you can access the phone's battery level and signal strength, or instruct the handset to vibrate. The syntax of fscommand2 is similar to the syntax of the fscommand function you might have used in Flash development for the Flash Desktop Player, except that fscommand2 allows you to pass multiple arguments to the specified command.

As an example, you might be developing a Flash Lite game. When the game is finished, you want to allow the user to quit by pressing the left soft key or play again by pressing the right soft key. You would add the following ActionScript to the last frame of the game:

 fscommand2("SetSoftKeys", "Quit", "Play Again"); 

Your new labels will be visible only if you have disabled FullScreen mode for your movie. FullScreen mode is set using another fscommand2 command, FullScreen. To disable FullScreen mode, issue the following command on the first frame of the movie:

 fscommand2("FullScreen", false); 

If you have created your Flash Lite document using the device templates method, there will already be a line of ActionScript on the first frame of your movie setting enabling FullScreen modein this case you will merely swap TRue for false in that command.

Note that even when the Soft Key labels are not visible, you still need to issue the Set-SoftKeys command if you wish to respond to the user pressing the soft keys.