Local FM Radio (Radio Tuner)

Local FM Radio provides a unique interface to your phone’s built-in FM radio tuner. Unlike the built-in radio app in the Music + Videos hub, this app enables you to directly type the frequency of your desired station. It also shows your current signal strength, which is an interesting little validation of any static you might be experiencing.

The purpose of this app is to demonstrate the phone’s simple but limited radio tuner API: the FMRadio class in the Microsoft.Devices.Radio namespace. Although the functionality exposed is very minimal, it comes with some nice perks, such as automatic integration into the Music + Video hub’s history/now playing lists.

The User Interface

As you can see from the screenshot to the right, this app’s user interface is a cross between Tip Calculator and Alarm Clock. Listing 32.1 contains the XAML for this app’s one and only page.

LISTING 32.1 MainPage.xaml—The User Interface for Local FM Radio

[code]

<phone:PhoneApplicationPage
x:Class=”WindowsPhoneApp.MainPage” x:Name=”Page”
xmlns=”http://schemas.microsoft.com/winfx/2006/xaml/presentation”
xmlns:x=”http://schemas.microsoft.com/winfx/2006/xaml”
xmlns:phone=”clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone”
xmlns:shell=”clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone”
xmlns:local=”clr-namespace:WindowsPhoneApp”
FontFamily=”{StaticResource PhoneFontFamilyNormal}”
FontSize=”{StaticResource PhoneFontSizeNormal}”
Foreground=”{StaticResource PhoneForegroundBrush}”
SupportedOrientations=”Portrait” shell:SystemTray.IsVisible=”True”>
<phone:PhoneApplicationPage.Resources>
<!– Style for calculator buttons –>
<Style x:Key=”CalculatorButtonStyle” TargetType=”Button”>
<Setter Property=”FontSize” Value=”36”/>
<Setter Property=”FontFamily”
Value=”{StaticResource PhoneFontFamilySemiLight}”/>
<Setter Property=”BorderThickness” Value=”0”/>
<Setter Property=”Width” Value=”132”/>
<Setter Property=”Height” Value=”108”/>
</Style>
</phone:PhoneApplicationPage.Resources>
<StackPanel Style=”{StaticResource PhoneTitlePanelStyle}”>
<TextBlock Text=”FM RADIO”
Style=”{StaticResource PhoneTextTitle0Style}”/>
<!– A user control much like the time display from Alarm Clock –>
<local:FrequencyDisplay x:Name=”FrequencyDisplay” Margin=”0,48”
HorizontalAlignment=”Center” FontSize=”220”/>
<!– The same calculator buttons from Tip Calculator, but with a
power button instead of a 00 button –>
<Canvas x:Name=”ButtonPanel” Height=”396” Margin=”-24,0”>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”7” Canvas.Left=”-6” Canvas.Top=”-1”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”8” Canvas.Left=”114” Canvas.Top=”-1”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”9” Canvas.Left=”234” Canvas.Top=”-1”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”4” Canvas.Top=”95” Canvas.Left=”-6”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”5” Canvas.Top=”95” Canvas.Left=”114”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”6” Canvas.Top=”95” Canvas.Left=”234”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”1” Canvas.Top=”191” Canvas.Left=”-6”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”2” Canvas.Top=”191” Canvas.Left=”114”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”3” Canvas.Top=”191” Canvas.Left=”234”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”0” Canvas.Top=”287” Canvas.Left=”-6”/>
<Button Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorMainBrush, ElementName=Page}”
Content=”power” Width=”252” Canvas.Top=”287” Canvas.Left=”114”/>
<Button Style=”{StaticResource CalculatorButtonStyle}” FontSize=”32”
FontFamily=”{StaticResource PhoneFontFamilySemiBold}”
Background=”{Binding CalculatorSecondaryBrush, ElementName=Page}”
Content=”C” Height=”204” Canvas.Top=”-1” Canvas.Left=”354”/>
<Button x:Name=”BackspaceButton” Height=”204”
Style=”{StaticResource CalculatorButtonStyle}”
Background=”{Binding CalculatorSecondaryBrush, ElementName=Page}”
Canvas.Top=”191” Canvas.Left=”354”>
<!– The “X in an arrow” backspace drawing –>
<Canvas Width=”48” Height=”32”>
<Path x:Name=”BackspaceXPath” Data=”M24,8 39,24 M39,8 24,24”
Stroke=”{StaticResource PhoneForegroundBrush}”
StrokeThickness=”4”/>
<Path x:Name=”BackspaceBorderPath” StrokeThickness=”2”
Data=”M16,0 47,0 47,31 16,31 0,16.5z”
Stroke=”{StaticResource PhoneForegroundBrush}”/>
</Canvas>
</Button>
</Canvas>
<!– A signal strength display –>
<TextBlock x:Name=”SignalStrengthTextBlock” Margin=”24”
HorizontalAlignment=”Center” />
</StackPanel>
</phone:PhoneApplicationPage>

[/code]

The Code-Behind

Listing 32.2 contains the code-behind for Local FM Radio.

LISTING 32.2 MainPage.xaml.cs—The Code-Behind for Local FM Radio

[code]

using System;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Threading;
using Microsoft.Devices.Radio;
using Microsoft.Phone.Controls;
namespace WindowsPhoneApp
{
public partial class MainPage : PhoneApplicationPage
{
double frequency;
DateTime? lastDigitButtonTap;
// Two theme-specific custom brushes
public Brush CalculatorMainBrush { get; set; }
public Brush CalculatorSecondaryBrush { get; set; }
public MainPage()
{
InitializeComponent();
// Ensure the radio is on
StartRadio();
// Work around having no radio events by polling
DispatcherTimer timer = new DispatcherTimer {
Interval = TimeSpan.FromSeconds(2) };
timer.Tick += delegate(object sender, EventArgs e) {
// Update the signal strength every two seconds
this.SignalStrengthTextBlock.Text = “signal strength: “ +
(FMRadio.Instance.SignalStrength * 100).ToString(“##0”);
};
timer.Start();
// A single handler for all calculator button taps
this.ButtonPanel.AddHandler(Button.MouseLeftButtonUpEvent,
new MouseButtonEventHandler(CalculatorButton_MouseLeftButtonUp),
true /* handledEventsToo */);
// Handlers to ensure that the backspace button’s vector content changes
// color appropriately when the button is pressed
this.BackspaceButton.AddHandler(Button.MouseLeftButtonDownEvent,
new MouseButtonEventHandler(BackspaceButton_MouseLeftButtonDown),
true /* handledEventsToo */);
this.BackspaceButton.AddHandler(Button.MouseLeftButtonUpEvent,
new MouseButtonEventHandler(BackspaceButton_MouseLeftButtonUp),
true /* handledEventsToo */);
this.BackspaceButton.MouseMove += BackspaceButton_MouseMove;
// Set the colors of the two custom brushes based on whether
// we’re in the light theme or dark theme
if ((Visibility)Application.Current.Resources[“PhoneLightThemeVisibility”]
== Visibility.Visible)
{
this.CalculatorMainBrush = new SolidColorBrush(
Color.FromArgb(0xFF, 0xEF, 0xEF, 0xEF));
this.CalculatorSecondaryBrush = new SolidColorBrush(
Color.FromArgb(0xFF, 0xDE, 0xDF, 0xDE));
}
else
{
this.CalculatorMainBrush = new SolidColorBrush(
Color.FromArgb(0xFF, 0x18, 0x1C, 0x18));
this.CalculatorSecondaryBrush = new SolidColorBrush(
Color.FromArgb(0xFF, 0x31, 0x30, 0x31));
}
// Grab the current frequency from the device’s radio
this.frequency = FMRadio.Instance.Frequency;
UpdateFrequencyDisplay();
}
void StartRadio()
{
try
{
// This would throw a RadioDisabledException if the app weren’t given
// the ID_CAP_MEDIALIB capability, but we’re worried instead about an
// UnauthorizedAccessException thrown when the phone is connected to Zune
FMRadio.Instance.PowerMode = RadioPowerMode.On;
}
catch
{
// Show a message explaining the limitation while connected to Zune
MessageBox.Show(“Be sure that your phone is disconnected from your “ +
“computer.”, “Cannot turn radio on”, MessageBoxButton.OK);
return;
}
if (FMRadio.Instance.SignalStrength == 0)
{
// Show a message similar to the built-in radio app
MessageBox.Show(“This phone uses your headphones as an FM radio “ +
“antenna. To listen to radio, connect your headphones.”, “No antenna”,
MessageBoxButton.OK);
}
}
void StopRadio()
{
try { FMRadio.Instance.PowerMode = RadioPowerMode.Off; }
catch {} // Ignore exception from being connected to Zune
}
// A single handler for all calculator button taps
void CalculatorButton_MouseLeftButtonUp(object sender, MouseButtonEventArgs e)
{
// Although sender is the canvas, the OriginalSource is the tapped button
Button button = e.OriginalSource as Button;
if (button == null)
return;
string content = button.Content.ToString();
// Determine what to do based on the string content of the tapped button
double digit;
if (content == “power”)
{
if (FMRadio.Instance.PowerMode == RadioPowerMode.On)
StopRadio();
else
StartRadio();
}
else if (double.TryParse(content, out digit)) // double so division works
{
// If there are already four digits (including the decimal place), or if
// the user hasn’t recently typed digits, clear the frequency first
if (this.frequency > 100 || this.lastDigitButtonTap == null ||
DateTime.Now – this.lastDigitButtonTap > TimeSpan.FromSeconds(3))
this.frequency = 0;
// Append the digit
this.frequency *= 10;
this.frequency += digit / 10;
this.lastDigitButtonTap = DateTime.Now;
}
else if (content == “C”)
{
// Clear the frequency
this.frequency = 0;
}
else // The backspace button
{
// Chop off the last digit (the decimal place) with a cast
int temp = (int)this.frequency;
// Shift right by 1 place
this.frequency = (double)temp / 10;
}
UpdateFrequencyDisplay();
}
void UpdateFrequencyDisplay()
{
try
{
this.FrequencyDisplay.Foreground =
Application.Current.Resources[“PhoneAccentBrush”] as Brush;
// Update the display
this.FrequencyDisplay.Frequency = this.frequency;
// Update the radio
FMRadio.Instance.Frequency = this.frequency;
}
catch
{
if (FMRadio.Instance.PowerMode == RadioPowerMode.On)
{
// Caused by an invalid frequency value, which easily
// happens while typing a valid frequency
this.FrequencyDisplay.Foreground = new SolidColorBrush(Colors.Red);
}
}
}
// Change the color of the two paths inside the backspace button when pressed
void BackspaceButton_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)
{
this.BackspaceXPath.Stroke =
Application.Current.Resources[“PhoneBackgroundBrush”] as Brush;
this.BackspaceBorderPath.Stroke =
Application.Current.Resources[“PhoneBackgroundBrush”] as Brush;
}
// Change the color of the two paths back when no longer pressed
void BackspaceButton_MouseLeftButtonUp(object sender, MouseEventArgs e)
{
this.BackspaceXPath.Stroke =
Application.Current.Resources[“PhoneForegroundBrush”] as Brush;
this.BackspaceBorderPath.Stroke =
Application.Current.Resources[“PhoneForegroundBrush”] as Brush;
}
// Workaround for when the finger has not yet been released but the color
// needs to change back because the finger is no longer over the button
void BackspaceButton_MouseMove(object sender, MouseEventArgs e)
{
// this.BackspaceButton.IsMouseOver lies when it has captured the mouse!
// Use GetPosition instead:
Point relativePoint = e.GetPosition(this.BackspaceButton);
// We can get away with this simple check because
// the button is in the bottom-right corner
if (relativePoint.X < 0 || relativePoint.Y < 0)
BackspaceButton_MouseLeftButtonUp(null, null); // Not over the button
else
BackspaceButton_MouseLeftButtonDown(null, null); // Still over the button
}
}
}

[/code]

• You can get an instance of the FMRadio class via the static FMRadio.Instance property. The instance exposes three read-write properties that control the phone’s single radio tuner exposed to all apps:
  • Frequency, a double value representing the current radio station.
  • PowerMode, which is either On or Off.
  • CurrentRegion, which can be UnitedStates, Japan, or Europe. The latter really means “every place in the world that isn’t the U.S. or Japan.”

It also exposes a read-only SignalStrength double property that exposes the received signal strength indicator (RSSI). The range of this value has not been documented, but it appears to be a value from 0 (no signal) to 1 (best signal), at least on the hardware I’ve tested.

Why doesn’t the radio work while my phone is connected to a computer running Zune?

The Zune desktop program locks the media library, which prevents any functionality that requires the ID_CAP_MEDIALIB capability from working. (This is the same reason you can’t use the phone’s Marketplace app while your phone is connected to Zune.) If you need to debug a part of your app that depends on such functionality, you can use the Windows Phone Connect Tool that ships with the Windows Phone Developer Tools to connect to your phone without Zune running.

There’s nothing that users of your app can do about this limitation other than closing Zune or disconnecting the phone, but it’s a good idea to detect this situation so you can explain what’s going on. Local FM Radio detects this situation inside its StartRadio method. It assumes that a failure to set PowerMode is due to the Zune connection, which is a pretty safe assumption.

Another way to detect this situation would be to see if the value of NetworkInterface. InterfaceType (in the Microsoft.Phone.Net.NetworkInformation namespace) is Ethernet, which should only happen when connected to Zune.However, this is a very bad property, because it performs long, blocking work before returning its value. If you decide to use it, be sure to do so on a background thread!

FMRadio’s Frequency property is a global setting!

If you change the radio station, this affects the built-in radio app (and any other third-party app consuming the radio tuner). On the one hand, this is handy, because an app doesn’t need to remember the last-used frequency when launched. (Indeed, the Local FM Radio app doesn’t persist anything to isolated storage.) On the other hand, you must do extra work if you wish to provide any sort of isolation from the built-in radio settings.

• Because the signal strength can constantly vary, but there are no radio-specific events exposed, MainPage’s constructor uses a timer to refresh the signal strength display every two seconds. Although this kind of polling is bad for battery life, it’s unlikely that a user will be running this app for very long. That’s because the radio can keep playing after the app has been exited (and, importantly, this app does not run under the lock screen). The constructor also initializes the frequency variable to whatever frequency the radio was previously set.
• The StartRadio and StopRadio methods toggle the value of the PowerMode property. StartRadio also shows a message similar to what the built-in radio app displays if the signal strength is zero, as shown in Figure 32.1. This app assumes that the user’s headphones must not be plugged in when this happens, as the headphones act as the FM antenna for every current phone model.

FMRadio’s PowerMode property is buggy in Version 7.0 of Windows Phone!

At least on some phones, setting PowerMode to Off stops the radio for a fraction of a second, but then the audio keeps playing even though the value of PowerMode doesn’t change back! This makes it impossible to show an on/off button that is in sync with the actual state of the radio. Instead, the power button in this app ends up acting strangely. Given this state of affairs, it’s only useful as a way to start the radio in case it couldn’t be started when the app launched (due to being connected to Zune).

• When the radio is on, setting the frequency to an invalid value throws an exception. Valid and invalid values are based on the current region, which would be complicated to detect with your own logic. Therefore, this app takes the easy way out and leverages the exception to turn the frequency display red. (Of course, if the current accent color is already red, then this behavior is not noticeable.)
• After the user has left the app (or while the app is still running), he/she can still control the radio by tapping the volume-up or volumedown button. This brings up the top overlay shown in Figure 32.2. Interestingly, this overlay enables seeking to the previous/next valid station (with the rewind and fastforward buttons), so the current station can get out-of-sync with the app’s own frequency display if this is done while Local FM Radio is running. Although this app could attempt to detect and correct this situation inside its timer’s Tick event handler, this is a minorenough issue to warrant leaving things as-is.

Can I retrieve the current radio station’s call letters, name, or “now playing” information?

No, although the built-in radio app can display this information, it is not exposed via any available APIs built into the phone.

The Finished Product