<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- capabilitiesexample.qdoc -->
<title>Qt 4.8: Capabilities Example</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="all-examples.html">Examples</a></li>
<li>Capabilities Example</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#window-class-definition">Window Class Definition</a></li>
<li class="level1"><a href="#window-class-implementation">Window Class Implementation</a></li>
<li class="level1"><a href="#the-main-function">The main() function</a></li>
</ul>
</div>
<h1 class="title">Capabilities Example</h1>
<span class="subtitle"></span>
<!-- $$$phonon/capabilities-description -->
<div class="descr"> <a name="details"></a>
<p>Files:</p>
<ul>
<li><a href="phonon-capabilities-window-cpp.html">phonon/capabilities/window.cpp</a></li>
<li><a href="phonon-capabilities-window-h.html">phonon/capabilities/window.h</a></li>
<li><a href="phonon-capabilities-main-cpp.html">phonon/capabilities/main.cpp</a></li>
<li><a href="phonon-capabilities-capabilities-pro.html">phonon/capabilities/capabilities.pro</a></li>
</ul>
<p>The Backend Capabilities example shows how to check which MIME types, audio devices, and audio effects are available.<p class="centerAlign"><img src="images/capabilitiesexample.png" alt="" /></p><p>Phonon does not implement the multimedia functionality itself, but relies on a backend to manage this. The backends do not manage the hardware directly, but use intermediate technologies: QuickTime on Mac, GStreamer on Linux, and DirectShow (which requires DirectX) on Windows.</p>
<p>The user may add support for new MIME types and effects to these systems, and the systems abilities may also be different. The support for multimedia MIME types, and audio effects in Phonon will therefore vary from system to system.</p>
<p>Backends informs the programmer about current capabilities through an implementation of the <a href="phonon-backendcapabilities.html">Phonon::BackendCapabilities</a> namespace. The backend reports which MIME types can be played back, which audio effects are available, and which sound devices are available on the system. When the capabilities of a backend changes, it will emit the <a href="phonon-backendcapabilities-notifier.html#capabilitiesChanged">capabilitiesChanged()</a> signal.</p>
<p>The example consists of one class, <tt>Window</tt>, which displays capabilities information from the current backend used by Phonon.</p>
<p>See the <a href="phonon-overview.html#phonon-overview">Phonon Overview</a> for a high-level introduction to Phonon.</p>
<a name="window-class-definition"></a>
<h2>Window Class Definition</h2>
<p>The <tt>Window</tt> class queries the Phonon backend for its capabilities. The results are presented in a GUI consisting of standard Qt widgets. We will now take a tour of the Phonon related parts of both the definition and implementation of the <tt>Window</tt> class.</p>
<pre class="cpp"> <span class="keyword">private</span> <span class="keyword">slots</span>:
<span class="type">void</span> updateWidgets();
<span class="keyword">private</span>:
<span class="type">void</span> setupUi();
<span class="type"><a href="qgroupbox.html">QGroupBox</a></span> <span class="operator">*</span>backendBox;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>devicesLabel;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>mimeTypesLabel;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>effectsLabel;
<span class="type"><a href="qlistwidget.html">QListWidget</a></span> <span class="operator">*</span>mimeListWidget;
<span class="type"><a href="qlistview.html">QListView</a></span> <span class="operator">*</span>devicesListView;
<span class="type"><a href="qtreewidget.html">QTreeWidget</a></span> <span class="operator">*</span>effectsTreeWidget;</pre>
<p>We need the slot to notice changes in the backends capabilities.</p>
<p><tt>mimeListWidget</tt> and <tt>devicesListView</tt> lists MIME types and audio devices. The <tt>effectsTreeWidget</tt> lists audio effects, and expands to show their parameters.</p>
<p>The <tt>setupUi()</tt> and <tt>setupBackendBox()</tt> private utility functions create the widgets and lays them out. We skip these functions while discussing the implementation because they do not contain Phonon relevant code.</p>
<a name="window-class-implementation"></a>
<h2>Window Class Implementation</h2>
<p>Our examination starts with a look at the constructor:</p>
<pre class="cpp"> Window<span class="operator">::</span>Window()
{
setupUi();
updateWidgets();
connect(Phonon<span class="operator">::</span>BackendCapabilities<span class="operator">::</span>notifier()<span class="operator">,</span>
SIGNAL(capabilitiesChanged())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(updateWidgets()));
connect(Phonon<span class="operator">::</span>BackendCapabilities<span class="operator">::</span>notifier()<span class="operator">,</span>
SIGNAL(availableAudioOutputDevicesChanged())<span class="operator">,</span> SLOT(updateWidgets()));
}</pre>
<p>After creating the user interface, we call <tt>updateWidgets()</tt>, which will fill the widgets with the information we get from the backend. We then connect the slot to the <a href="phonon-backendcapabilities-notifier.html#capabilitiesChanged">capabilitiesChanged()</a> and <a href="phonon-backendcapabilities-notifier.html#availableAudioOutputDevicesChanged">availableAudioOutputDevicesChanged()</a> signals in case the backend's abilities changes while the example is running. The signal is emitted by a <a href="phonon-backendcapabilities-notifier.html">Phonon::BackendCapabilities::Notifier</a> object, which listens for changes in the backend.</p>
<p>In the <tt>updateWidgets()</tt> function, we query the backend for information it has about its abilities and present it in the GUI of <tt>Window</tt>. We dissect it here:</p>
<pre class="cpp"> <span class="type">void</span> Window<span class="operator">::</span>updateWidgets()
{
devicesListView<span class="operator">-</span><span class="operator">></span>setModel(<span class="keyword">new</span> <span class="type"><a href="qstandarditemmodel.html">QStandardItemModel</a></span>());
Phonon<span class="operator">::</span>ObjectDescriptionModel<span class="operator"><</span>Phonon<span class="operator">::</span>AudioOutputDeviceType<span class="operator">></span> <span class="operator">*</span>model <span class="operator">=</span>
<span class="keyword">new</span> Phonon<span class="operator">::</span>ObjectDescriptionModel<span class="operator"><</span>Phonon<span class="operator">::</span>AudioOutputDeviceType<span class="operator">></span>();
model<span class="operator">-</span><span class="operator">></span>setModelData(Phonon<span class="operator">::</span>BackendCapabilities<span class="operator">::</span>availableAudioOutputDevices());
devicesListView<span class="operator">-</span><span class="operator">></span>setModel(model);</pre>
<p>The <a href="phonon-backendcapabilities-notifier.html#availableAudioOutputDevicesChanged">availableAudioOutputDevicesChanged()</a> function is a member of the <a href="phonon-backendcapabilities.html">Phonon::BackendCapabilities</a> namespace. It returns a list of <a href="phonon-objectdescription.html#AudioOutputDevice-typedef">AudioOutputDevice</a>s, which gives us information about a particular device, e.g., a sound card or a USB headset.</p>
<p>Note that <a href="phonon-objectdescription.html#AudioOutputDevice-typedef">AudioOutputDevice</a> and also <a href="phonon-objectdescription.html#EffectDescription-typedef">EffectDescription</a>, which is described shortly, are typedefs of <a href="phonon-objectdescription.html#ObjectDescriptionType-enum">ObjectDescriptionType</a>.</p>
<pre class="cpp"> mimeListWidget<span class="operator">-</span><span class="operator">></span>clear();
<span class="type"><a href="qstringlist.html">QStringList</a></span> mimeTypes <span class="operator">=</span>
Phonon<span class="operator">::</span>BackendCapabilities<span class="operator">::</span>availableMimeTypes();
foreach (<span class="type"><a href="qstring.html">QString</a></span> mimeType<span class="operator">,</span> mimeTypes) {
<span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span> <span class="operator">*</span>item <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qlistwidgetitem.html">QListWidgetItem</a></span>(mimeListWidget);
item<span class="operator">-</span><span class="operator">></span>setText(mimeType);
}</pre>
<p>The MIME types supported are given as strings in a <a href="qstringlist.html">QStringList</a>. We can therefore create a list widget item with the string, and append it to the <tt>mimeListWidget</tt>, which displays the available MIME types.</p>
<pre class="cpp"> effectsTreeWidget<span class="operator">-</span><span class="operator">></span>clear();
<span class="type"><a href="qlist.html">QList</a></span><span class="operator"><</span>Phonon<span class="operator">::</span>EffectDescription<span class="operator">></span> effects <span class="operator">=</span>
Phonon<span class="operator">::</span>BackendCapabilities<span class="operator">::</span>availableAudioEffects();
foreach (Phonon<span class="operator">::</span>EffectDescription effect<span class="operator">,</span> effects) {
<span class="type"><a href="qtreewidgetitem.html">QTreeWidgetItem</a></span> <span class="operator">*</span>item <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qtreewidgetitem.html">QTreeWidgetItem</a></span>(effectsTreeWidget);
item<span class="operator">-</span><span class="operator">></span>setText(<span class="number">0</span><span class="operator">,</span> tr(<span class="string">"Effect"</span>));
item<span class="operator">-</span><span class="operator">></span>setText(<span class="number">1</span><span class="operator">,</span> effect<span class="operator">.</span>name());
item<span class="operator">-</span><span class="operator">></span>setText(<span class="number">2</span><span class="operator">,</span> effect<span class="operator">.</span>description());</pre>
<p>As before we add the description and name to our widget, which in this case is a <a href="qtreewidget.html">QTreeWidget</a>. A particular effect may also have parameters, which are inserted in the tree as child nodes of their effect.</p>
<pre class="cpp"> Phonon<span class="operator">::</span>Effect <span class="operator">*</span>instance <span class="operator">=</span> <span class="keyword">new</span> Phonon<span class="operator">::</span>Effect(effect<span class="operator">,</span> <span class="keyword">this</span>);
<span class="type"><a href="qlist.html">QList</a></span><span class="operator"><</span>Phonon<span class="operator">::</span>EffectParameter<span class="operator">></span> parameters <span class="operator">=</span> instance<span class="operator">-</span><span class="operator">></span>parameters();
<span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">0</span>; i <span class="operator"><</span> parameters<span class="operator">.</span>size(); <span class="operator">+</span><span class="operator">+</span>i) {
Phonon<span class="operator">::</span>EffectParameter parameter <span class="operator">=</span> parameters<span class="operator">.</span>at(i);
<span class="type"><a href="qvariant.html">QVariant</a></span> defaultValue <span class="operator">=</span> parameter<span class="operator">.</span>defaultValue();
<span class="type"><a href="qvariant.html">QVariant</a></span> minimumValue <span class="operator">=</span> parameter<span class="operator">.</span>minimumValue();
<span class="type"><a href="qvariant.html">QVariant</a></span> maximumValue <span class="operator">=</span> parameter<span class="operator">.</span>maximumValue();
<span class="type"><a href="qstring.html">QString</a></span> valueString <span class="operator">=</span> <span class="type"><a href="qstring.html">QString</a></span>(<span class="string">"%1 / %2 / %3"</span>)
<span class="operator">.</span>arg(defaultValue<span class="operator">.</span>toString())<span class="operator">.</span>arg(minimumValue<span class="operator">.</span>toString())
<span class="operator">.</span>arg(maximumValue<span class="operator">.</span>toString());
<span class="type"><a href="qtreewidgetitem.html">QTreeWidgetItem</a></span> <span class="operator">*</span>parameterItem <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qtreewidgetitem.html">QTreeWidgetItem</a></span>(item);
parameterItem<span class="operator">-</span><span class="operator">></span>setText(<span class="number">0</span><span class="operator">,</span> tr(<span class="string">"Parameter"</span>));
parameterItem<span class="operator">-</span><span class="operator">></span>setText(<span class="number">1</span><span class="operator">,</span> parameter<span class="operator">.</span>name());
parameterItem<span class="operator">-</span><span class="operator">></span>setText(<span class="number">2</span><span class="operator">,</span> parameter<span class="operator">.</span>description());
parameterItem<span class="operator">-</span><span class="operator">></span>setText(<span class="number">3</span><span class="operator">,</span> <span class="type"><a href="qvariant.html">QVariant</a></span><span class="operator">::</span>typeToName(parameter<span class="operator">.</span>type()));
parameterItem<span class="operator">-</span><span class="operator">></span>setText(<span class="number">4</span><span class="operator">,</span> valueString);
}
}</pre>
<p>The parameters are only accessible through an instance of the <a href="phonon-effect.html">Effect</a> class. Notice that an effect is created with the effect description.</p>
<p>The <a href="phonon-effectparameter.html">EffectParameter</a> contains information about one of an effects parameters. We pick out some of the information to describe the parameter in the tree widget.</p>
<a name="the-main-function"></a>
<h2>The main() function</h2>
<p>Because Phonon uses D-Bus on Linux, it is necessary to give the application a name. You do this with <a href="qcoreapplication.html#applicationName-prop">setApplicationName()</a>.</p>
<pre class="cpp"> <span class="type">int</span> main(<span class="type">int</span> argv<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span><span class="operator">*</span>args)
{
<span class="type"><a href="qapplication.html">QApplication</a></span> app(argv<span class="operator">,</span> args);
app<span class="operator">.</span>setApplicationName(<span class="string">"Phonon Capabilities Example"</span>);
Window window;
<span class="preprocessor">#if defined(Q_OS_SYMBIAN)</span>
window<span class="operator">.</span>showMaximized();
<span class="preprocessor">#else</span>
window<span class="operator">.</span>show();
<span class="preprocessor">#endif</span>
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}</pre>
</div>
<!-- @@@phonon/capabilities -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
