net.rim.device.api.amms.control.fmradio
Class FmRadioLocale

java.lang.Object
  extended by net.rim.device.api.amms.control.fmradio.FmRadioLocale

public class FmRadioLocale
extends Object

Represents the regional characteristics of FM radio reception. These characteristics optimize radio signal reception based for the region. This class configures the frequency band and frequency step parameters of FmTunerControl.seek(). Differences can be observed in the following parameters of the implementation:

Technical Details

The locale is set by the BlackBerry device and the API can only be used to update the UI properly or set seek parameters according to the set locale. Use the FmTunerControl.getLocale() method to retrieve an FmRadioLocale object that you can use to fine configure your application according to the regional settings.

See Also:
FmTunerControl
Since:
BlackBerry API 7.1.0

Field Summary
static int BAND_CCIR
          FM band outside of Japan (87.5-108MHz)
static int BAND_JAPAN
          FM band in Japan (76-90MHz).
static int EMPHASIS_50_US
          FM Emphasis used outside of North America
static int EMPHASIS_75_US
          FM Emphasis used in North America
static FmRadioLocale LOCALE_AMERICA
          FM Locale for North America.
static FmRadioLocale LOCALE_JAPAN
          FM Locale for Japan.
static FmRadioLocale LOCALE_OTHERS
          FM Locale for other countries.
static FmRadioLocale LOCALE_OTHERS_STEP_50
          FM Locale for other countries using a frequency step of 50kHz like Italy and Thailand.
static int STEP_100_KHZ
          FM step used mostly in the rest of the world outside of North America
static int STEP_200_KHZ
          FM step used in North America
static int STEP_50_KHZ
          FM step
 
Constructor Summary
FmRadioLocale(int band, int maxFreq, int minFreq, int step, boolean isEvenOffset, int emphasis)
          Constructor.
 
Method Summary
 int clampFrequency(int freq)
          Clamps the specified frequency into this locale's valid range.
 boolean equals(Object obj)
          Indicates whether two FmRadioLocale objects are equal by checking their FM data (band, minFreq, maxFreq, step, offset, and emphasis).
 int getBand()
          Gets the FM band.
 int getEmphasis()
          Gets the FM emphasis.
 int getFrequencyDigitsAfterDecimal()
          Checks the FM step size to be 50kHz.
 int getMaxFreq()
          Gets the maximum frequency for this locale.
 int getMinFreq()
          Gets the minimum frequency for this locale.
static FmRadioLocale[] getPredefined()
          Gets a list of predefined FmRadioLocale objects.
 int getStep()
          Gets the FM step.
static int[] getValidEmphases()
          Gets a list of valid FM emphasis.
static int[] getValidSteps()
          Gets a list of valid FM steps.
 int hashCode()
          Creates a unique hashcode for this object.
 boolean isEvenOffset()
          Gets the FM offset.
 boolean isFrequencyInRange(int freq)
          Indicates whether the frequency is valid in the range defined for the locale.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

BAND_CCIR

public static final int BAND_CCIR
FM band outside of Japan (87.5-108MHz)

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

BAND_JAPAN

public static final int BAND_JAPAN
FM band in Japan (76-90MHz).

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

STEP_200_KHZ

public static final int STEP_200_KHZ
FM step used in North America

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

STEP_100_KHZ

public static final int STEP_100_KHZ
FM step used mostly in the rest of the world outside of North America

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

STEP_50_KHZ

public static final int STEP_50_KHZ
FM step

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

EMPHASIS_75_US

public static final int EMPHASIS_75_US
FM Emphasis used in North America

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

EMPHASIS_50_US

public static final int EMPHASIS_50_US
FM Emphasis used outside of North America

See Also:
Constant Field Values
Since:
BlackBerry API 7.1.0

LOCALE_JAPAN

public static final FmRadioLocale LOCALE_JAPAN
FM Locale for Japan. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is Japan.

Since:
BlackBerry API 7.1.0

LOCALE_AMERICA

public static final FmRadioLocale LOCALE_AMERICA
FM Locale for North America. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is North America.

Since:
BlackBerry API 7.1.0

LOCALE_OTHERS

public static final FmRadioLocale LOCALE_OTHERS
FM Locale for other countries. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is outside of Japan and North America.

Since:
BlackBerry API 7.1.0

LOCALE_OTHERS_STEP_50

public static final FmRadioLocale LOCALE_OTHERS_STEP_50
FM Locale for other countries using a frequency step of 50kHz like Italy and Thailand. Useful when comparing a retrieved locale using the equals() method to determine whether the set locale is outside of Japan and North America.

Since:
BlackBerry API 7.1.0


Constructor Detail

FmRadioLocale

public FmRadioLocale(int band,
                     int maxFreq,
                     int minFreq,
                     int step,
                     boolean isEvenOffset,
                     int emphasis)
Constructor.

Parameters:
band - The FM band to be set.
maxFreq - The upper frequency band-limit of the locale in 100Hz.
minFreq - The lower frequency band-limit of the locale in 100Hz.
step - The FM step to be set.
isEvenOffset - true even offset; false odd offset.
emphasis - The FM emphasis to be set.
Throws:
IllegalArgumentException - If the band is not either BAND_JAPAN or BAND_CCIR; If the step is not STEP_200_KHZ or STEP_100_KHZ or STEP_50_KHZ; If the emphasis is not EMPHASIS_75_US or EMPHASIS_50_US
Since:
BlackBerry API 7.1.0


Method Detail

getStep

public int getStep()
Gets the FM step.

Returns:
one of the STEP_200_KHZ or STEP_100_KHZ or STEP_50_KHZ constants defined in this class.
Since:
BlackBerry API 7.1.0

getFrequencyDigitsAfterDecimal

public int getFrequencyDigitsAfterDecimal()
Checks the FM step size to be 50kHz. This can be helpful for displaying frequencies with one or two digits after the decimal point.

Returns:
2, if the step equals STEP_50_KHZ, 1, otherwise.
Since:
BlackBerry API 7.1.0

isEvenOffset

public boolean isEvenOffset()
Gets the FM offset.

Returns:
true if the offset is even; false otherwise.
Since:
BlackBerry API 7.1.0

getEmphasis

public int getEmphasis()
Gets the FM emphasis.

Returns:
one of the EMPHASIS_75_US or EMPHASIS_50_US constants defined in this class.
Since:
BlackBerry API 7.1.0

getBand

public int getBand()
Gets the FM band.

Returns:
one of the BAND_JAPAN or BAND_CCIR constants defined in this class.
Since:
BlackBerry API 7.1.0

equals

public boolean equals(Object obj)
Indicates whether two FmRadioLocale objects are equal by checking their FM data (band, minFreq, maxFreq, step, offset, and emphasis).

Overrides:
equals in class Object
Parameters:
obj - An FMRadioLocale object.
Returns:
true if the two locale objects have the same FM data; false otherwise.
See Also:
Boolean.hashCode(), Hashtable
Since:
BlackBerry API 7.1.0

hashCode

public int hashCode()
Creates a unique hashcode for this object.

Overrides:
hashCode in class Object
Returns:
a unique hashcode based on the different possible locale attributes.
See Also:
Object.equals(java.lang.Object), Hashtable
Since:
BlackBerry API 7.1.0

getPredefined

public static FmRadioLocale[] getPredefined()
Gets a list of predefined FmRadioLocale objects.

Returns:
a newly-created array containing each of the LOCALE_ constants defined in this class.
Since:
BlackBerry API 7.1.0

getValidSteps

public static int[] getValidSteps()
Gets a list of valid FM steps.

Returns:
a newly-created array containing each of the STEP_ constants defined in this class.
Since:
BlackBerry API 7.1.0

getValidEmphases

public static int[] getValidEmphases()
Gets a list of valid FM emphasis.

Returns:
a newly-created array containing each of the EMPHASIS_ constants defined in this class.
Since:
BlackBerry API 7.1.0

getMinFreq

public int getMinFreq()
Gets the minimum frequency for this locale.

Returns:
frequency The minimum frequency for this locale in 100Hz.
Since:
BlackBerry API 7.1.0

getMaxFreq

public int getMaxFreq()
Gets the maximum frequency for this locale.

Returns:
frequency The maximum frequency for this locale in 100Hz.
Since:
BlackBerry API 7.1.0

isFrequencyInRange

public boolean isFrequencyInRange(int freq)
Indicates whether the frequency is valid in the range defined for the locale.

Parameters:
frequency - The desired frequency.
Returns:
true if the frequency is valid in the locale's range; false otherwise.
Since:
BlackBerry API 7.1.0

clampFrequency

public int clampFrequency(int freq)
Clamps the specified frequency into this locale's valid range. This method returns:

Parameters:
frequency - The desired frequency.
Returns:
The nearest valid frequency for the locale.
Since:
BlackBerry API 7.1.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal