slapin/qtmultimedia
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Added documentation for the Radio and RadioData QML elements.

Browse Source 
Change-Id: I60c98b23138664543a1738ae93043432f66c8ab8
Reviewed-by: Michael Goddard <michael.goddard@nokia.com>
This commit is contained in:
Jonas Rabbe
2012-01-10 14:32:56 +10:00
committed by Qt by Nokia
parent f7bfcdfa28
commit 99b80809c7
2 changed files with 422 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

276
src/imports/multimedia/qdeclarativeradio.cpp
View File

@@ -43,6 +43,55 @@
QT_BEGIN_NAMESPACE
/*!
\qmlclass Radio QDeclarativeRadio
\since 5.0.0
\brief The Radio element allows you to access radio functionality from a QML application.
\ingroup qml-multimedia
\inherits Item
This element is part of the \bold{QtMultimedia 5.0} module.
\qml
import QtQuick 2.0
import QtMultimedia 5.0
Rectangle {
width: 320
height: 480
Radio {
id: radio
band: Radio.FM
}
MouseArea {
x: 0; y: 0
height: parent.height
width: parent.width / 2
onClicked: radio.scanDown()
}
MouseArea {
x: parent.width / 2; y: 0
height: parent.height
width: parent.width / 2
onClicked: radio.scanUp()
}
}
\endqml
You can use the \c Radio element to tune the radio and get information about the signal.
You can also use the Radio element to get information about tuning, for instance the
frequency steps supported for tuning.
The corresponding \l RadioData element gives RDS information about the current radio station.
*/
QDeclarativeRadio::QDeclarativeRadio(QObject *parent) :
QObject(parent),
m_radioTuner(0)
@@ -67,66 +116,187 @@ QDeclarativeRadio::~QDeclarativeRadio()
{
}
/*!
\qmlproperty enumeration Radio::state
This property holds the current state of the Radio element.
\table
\header \o Value \o Description
\row \o ActiveState
\o The radio is started and active
\row \o StoppedState
\o The radio is stopped
\endtable
\sa start, stop
*/
QDeclarativeRadio::State QDeclarativeRadio::state() const
{
return static_cast<QDeclarativeRadio::State>(m_radioTuner->state());
}
/*!
\qmlproperty enumeration Radio::band
This property holds the frequency band used for the radio, which can be specified as
any one of the values in the table below.
\table
\header \o Value \o Description
\row \o AM
\o 520 to 1610 kHz, 9 or 10kHz channel spacing, extended 1610 to 1710 kHz
\row \o FM
\o 87.5 to 108.0 MHz, except Japan 76-90 MHz
\row \o SW
\o 1.711 to 30.0 MHz, divided into 15 bands. 5kHz channel spacing
\row \o LW
\o 148.5 to 283.5 kHz, 9kHz channel spacing (Europe, Africa, Asia)
\row \o FM2
\o range not defined, used when area supports more than one FM range
\endtable
*/
QDeclarativeRadio::Band QDeclarativeRadio::band() const
{
return static_cast<QDeclarativeRadio::Band>(m_radioTuner->band());
}
/*!
\qmlproperty int Radio::frequency
Sets the frequency in Hertz that the radio is tuned to. The frequency must be within the frequency
range for the current band, otherwise it will be changed to be within the frequency range.
\sa maximumFrequency, minimumFrequency
*/
int QDeclarativeRadio::frequency() const
{
return m_radioTuner->frequency();
}
/*!
\qmlproperty enumeration Radio::stereoMode
This property holds the stereo mode of the radio, which can be set to any one of the
values in the table below.
\table
\header \o Value \o Description
\row \o Auto
\o Uses stereo mode matching the station
\row \o ForceStereo
\o Forces the radio to play the station in stereo, converting the sound signal if necessary
\row \o ForceMono
\o Forces the radio to play the station in mono, converting the sound signal if necessary
\endtable
*/
QDeclarativeRadio::StereoMode QDeclarativeRadio::stereoMode() const
{
return static_cast<QDeclarativeRadio::StereoMode>(m_radioTuner->stereoMode());
}
/*!
\qmlproperty int Radio::volume
Set this property to control the volume of the radio. The valid range of the volume is from 0 to 100.
*/
int QDeclarativeRadio::volume() const
{
return m_radioTuner->volume();
}
/*!
\qmlproperty bool Radio::muted
This property reflects whether the radio is muted or not.
*/
bool QDeclarativeRadio::muted() const
{
return m_radioTuner->isMuted();
}
/*!
\qmlproperty bool Radio::stereo
This property holds whether the radio is receiving a stereo signal or not. If \l stereoMode is
set to ForceMono the value will always be false. Likewise, it will always be true if stereoMode
is set to ForceStereo.
\sa stereoMode
*/
bool QDeclarativeRadio::stereo() const
{
return m_radioTuner->isStereo();
}
/*!
\qmlproperty int Radio::signalStrength
The strength of the current radio signal as a percentage where 0% equals no signal, and 100% is a
very good signal.
*/
int QDeclarativeRadio::signalStrength() const
{
return m_radioTuner->signalStrength();
}
/*!
\qmlproperty bool Radio::searching
This property is true if the radio is currently searching for radio stations, for instance using the \l scanUp,
\l scanDown, and \l searchAllStations methods. Once the search completes, or if it is cancelled using
\l cancelScan, this property will be false.
*/
bool QDeclarativeRadio::searching() const
{
return m_radioTuner->isSearching();
}
/*!
\qmlproperty int Radio::frequencyStep
The number of Hertz for each step when tuning the radio manually. The value is for the current \l band.
*/
int QDeclarativeRadio::frequencyStep() const
{
return m_radioTuner->frequencyStep(m_radioTuner->band());
}
/*!
\qmlproperty int Radio::minimumFrequency
The minimum frequency for the current \l band.
*/
int QDeclarativeRadio::minimumFrequency() const
{
return m_radioTuner->frequencyRange(m_radioTuner->band()).first;
}
/*!
\qmlproperty int Radio::maximumFrequency
The maximum frequency for the current \l band.
*/
int QDeclarativeRadio::maximumFrequency() const
{
return m_radioTuner->frequencyRange(m_radioTuner->band()).second;
}
/*!
\qmlmethod bool Radio::isAvailable()
Returns whether the radio is ready to use.
*/
bool QDeclarativeRadio::isAvailable() const
{
return m_radioTuner->isAvailable();
@@ -157,26 +327,103 @@ void QDeclarativeRadio::setMuted(bool muted)
m_radioTuner->setMuted(muted);
}
/*!
\qmlmethod Radio::cancelScan()
Cancel the current scan. Will also cancel a search started with \l searchAllStations.
*/
void QDeclarativeRadio::cancelScan()
{
m_radioTuner->cancelSearch();
}
/*!
\qmlmethod Radio::scanDown()
Searches backward in the frequency range for the current band.
*/
void QDeclarativeRadio::scanDown()
{
m_radioTuner->searchBackward();
}
/*!
\qmlmethod Radio::scanUp()
Searches forward in the frequency range for the current band.
*/
void QDeclarativeRadio::scanUp()
{
m_radioTuner->searchForward();
}
/*!
\qmlmethod Radio::searchAllStations(enumeration searchMode)
Start searching the complete frequency range for the current band, and save all the
radio stations found. The search mode can be either of the values described in the
table below.
\table
\header \o Value \o Description
\row \o SearchFast
\o Stores each radio station for later retrival and tuning
\row \o SearchGetStationId
\o Does the same as SearchFast, but also emits the station Id with the \l stationFound signal.
\endtable
The snippet below uses \c searchAllStations with \c SearchGetStationId to receive all the radio
stations in the current band, and store them in a ListView. The station Id is shown to the user
and if the user presses a station, the radio is tuned to this station.
\qml
Radio {
id: radio
onStationFound: radioStations.append({"frequency": frequency, "stationId": stationId})
}
ListModel {
id: radioStations
}
ListView {
model: radioStations
delegate: Rectangle {
MouseArea {
anchors.fill: parent
onClicked: radio.frequency = frequency
}
Text {
anchors.fill: parent
text: stationId
}
}
}
Rectangle {
MouseArea {
anchors.fill: parent
onClicked: radio.searchAllStations(Radio.SearchGetStationId)
}
}
\endqml
*/
void QDeclarativeRadio::searchAllStations(QDeclarativeRadio::SearchMode searchMode)
{
m_radioTuner->searchAllStations(static_cast<QRadioTuner::SearchMode>(searchMode));
}
/*!
\qmlmethod Radio::tuneDown()
Decrements the frequency by the frequency step for the current band. If the frequency is already set
to the minimum frequency, calling this function has no effect.
\sa band, frequencyStep, minimumFrequency
*/
void QDeclarativeRadio::tuneDown()
{
int f = frequency();
@@ -184,6 +431,14 @@ void QDeclarativeRadio::tuneDown()
setFrequency(f);
}
/*!
\qmlmethod Radio::tuneUp()
Increments the frequency by the frequency step for the current band. If the frequency is already set
to the maximum frequency, calling this function has no effect.
\sa band, frequencyStep, maximumFrequency
*/
void QDeclarativeRadio::tuneUp()
{
int f = frequency();
@@ -191,11 +446,22 @@ void QDeclarativeRadio::tuneUp()
setFrequency(f);
}
/*!
\qmlmethod Radio::start()
Starts the radio. If the radio is available, as determined by the \l isAvailable method,
this will result in the \l state becoming \c ActiveState.
*/
void QDeclarativeRadio::start()
{
m_radioTuner->start();
}
/*!
\qmlmethod Radio::stop()
Stops the radio. After calling this method the \l state will be \c StoppedState.
*/
void QDeclarativeRadio::stop()
{
m_radioTuner->stop();
@@ -217,4 +483,14 @@ void QDeclarativeRadio::_q_error(QRadioTuner::Error errorCode)
emit errorChanged();
}
/*!
\qmlsignal Radio::stationFound(int frequency, string stationId)
This signal is emitted when a new radio station is found. This signal is only emitted
if \l searchAllStations is called with \c SearchGetStationId.
The \a frequency is returned in Hertz, and the \a stationId corresponds to the station Id
in the \l RadioData element for this radio station.
*/
QT_END_NAMESPACE

146
src/imports/multimedia/qdeclarativeradiodata.cpp
View File

@@ -43,6 +43,57 @@
QT_BEGIN_NAMESPACE
/*!
\qmlclass RadioData QDeclarativeRadioData
\since 5.0.0
\brief The RadioData element allows you to access RDS data from a QML application.
\ingroup qml-multimedia
\inherits Item
This element is part of the \bold{QtMultimedia 5.0} module.
The \c RadioData element is your gateway to all the data available through RDS. RDS is the Radio Data System
which allows radio stations to broadcast information like the \l stationId, \l programType, \l programTypeName,
\l stationName, and \l radioText. This information can be read from the \c RadioData element. It also allows
you to set whether the radio should tune to alternative frequencies if the current signal strength falls too much.
\qml
import QtQuick 2.0
import QtMultimedia 5.0
Rectangle {
width: 480
height: 320
Radio {
id: radio
band: Radio.FM
}
RadioData {
id: radioData
}
Column {
Text {
text: radioData.stationName
}
Text {
text: radioData.programTypeName
}
Text {
text: radioData.radioText
}
}
}
\endqml
You use \c RadioData together with the \l Radio element. The properties of the RadioData element will reflect the
information broadcast by the radio station the Radio element is currently tuned to.
*/
QDeclarativeRadioData::QDeclarativeRadioData(QObject *parent) :
QObject(parent),
m_radioData(0)
@@ -66,36 +117,131 @@ QDeclarativeRadioData::~QDeclarativeRadioData()
{
}
/*!
\qmlmethod bool RadioData::isAvailable()
Returns whether the radio data element is ready to use.
*/
bool QDeclarativeRadioData::isAvailable() const
{
return m_radioData->isAvailable();
}
/*!
\qmlproperty string RadioData::stationId
This property allows you to read the station Id of the currently tuned radio
station.
*/
QString QDeclarativeRadioData::stationId() const
{
return m_radioData->stationId();
}
/*!
\qmlproperty enumeration RadioData::programType
This property holds the type of the currently playing program as transmitted
by the radio station. The value can be any one of the values defined in the
table below.
\table
\header \o Value
\row \o Undefined
\row \o News
\row \o CurrentAffairs
\row \o Information
\row \o Sport
\row \o Education
\row \o Drama
\row \o Culture
\row \o Science
\row \o Varied
\row \o PopMusic
\row \o RockMusic
\row \o EasyListening
\row \o LightClassical
\row \o SeriousClassical
\row \o OtherMusic
\row \o Weather
\row \o Finance
\row \o ChildrensProgrammes
\row \o SocialAffairs
\row \o Religion
\row \o PhoneIn
\row \o Travel
\row \o Leisure
\row \o JazzMusic
\row \o CountryMusic
\row \o NationalMusic
\row \o OldiesMusic
\row \o FolkMusic
\row \o Documentary
\row \o AlarmTest
\row \o Alarm
\row \o Talk
\row \o ClassicRock
\row \o AdultHits
\row \o SoftRock
\row \o Top40
\row \o Soft
\row \o Nostalgia
\row \o Classical
\row \o RhythmAndBlues
\row \o SoftRhythmAndBlues
\row \o Language
\row \o ReligiousMusic
\row \o ReligiousTalk
\row \o Personality
\row \o Public
\row \o College
\endtable
*/
QDeclarativeRadioData::ProgramType QDeclarativeRadioData::programType() const
{
return static_cast<QDeclarativeRadioData::ProgramType>(m_radioData->programType());
}
/*!
\qmlproperty string RadioData::programTypeName
This property holds a string representation of the \l programType.
*/
QString QDeclarativeRadioData::programTypeName() const
{
return m_radioData->programTypeName();
}
/*!
\qmlproperty string RadioData::stationName
This property has the name of the currently tuned radio station.
*/
QString QDeclarativeRadioData::stationName() const
{
return m_radioData->stationName();
}
/*!
\qmlproperty string RadioData::radioText
This property holds free-text transmitted by the radio station. This is typically used to
show supporting information for the currently playing content, for instance song title or
artist name.
*/
QString QDeclarativeRadioData::radioText() const
{
return m_radioData->radioText();
}
/*!
\qmlproperty bool RadioData::alternativeFrequenciesEnabled
This property allows you to specify whether the radio should try and tune to alternative
frequencies if the signal strength of the current station becomes too weak. The alternative
frequencies are emitted over RDS by the radio station, and the tuning happens automatically.
*/
bool QDeclarativeRadioData::alternativeFrequenciesEnabled() const
{
return m_radioData->isAlternativeFrequenciesEnabled();