Capabilities Example

Window Class Implementation

Our examination starts with a look at the constructor:

 Window::Window()
 {
     setupUi();
     updateWidgets();

     connect(Phonon::BackendCapabilities::notifier(),
             SIGNAL(capabilitiesChanged()), this, SLOT(updateWidgets()));
     connect(Phonon::BackendCapabilities::notifier(),
             SIGNAL(availableAudioOutputDevicesChanged()), SLOT(updateWidgets()));
 }

After creating the user interface, we call updateWidgets(), which will fill the widgets with the information we get from the backend. We then connect the slot to the capabilitiesChanged() and availableAudioOutputDevicesChanged() signals in case the backend's abilities changes while the example is running. The signal is emitted by a Phonon::BackendCapabilities::Notifier object, which listens for changes in the backend.

In the updateWidgets() function, we query the backend for information it has about its abilities and present it in the GUI of Window. We dissect it here:

 void Window::updateWidgets()
 {
     devicesListView->setModel(new QStandardItemModel());
     Phonon::ObjectDescriptionModel<Phonon::AudioOutputDeviceType> *model =
             new Phonon::ObjectDescriptionModel<Phonon::AudioOutputDeviceType>();
     model->setModelData(Phonon::BackendCapabilities::availableAudioOutputDevices());
     devicesListView->setModel(model);

The availableAudioOutputDevicesChanged() function is a member of the Phonon::BackendCapabilities namespace. It returns a list of AudioOutputDevices, which gives us information about a particular device, e.g., a sound card or a USB headset.

Note that AudioOutputDevice and also EffectDescription, which is described shortly, are typedefs of ObjectDescriptionType.

The ObjectDescriptionModel is a convenience model that displays the names of the devices. Their descriptions are shown as tooltips and disabled devices are shown in gray.

     mimeListWidget->clear();
     QStringList mimeTypes =
             Phonon::BackendCapabilities::availableMimeTypes();
     foreach (QString mimeType, mimeTypes) {
         QListWidgetItem *item = new QListWidgetItem(mimeListWidget);
         item->setText(mimeType);
     }

The MIME types supported are given as strings in a QStringList. We can therefore create a list widget item with the string, and append it to the mimeListWidget, which displays the available MIME types.

     effectsTreeWidget->clear();
     QList<Phonon::EffectDescription> effects =
         Phonon::BackendCapabilities::availableAudioEffects();
     foreach (Phonon::EffectDescription effect, effects) {
         QTreeWidgetItem *item = new QTreeWidgetItem(effectsTreeWidget);
         item->setText(0, tr("Effect"));
         item->setText(1, effect.name());
         item->setText(2, effect.description());

As before we add the description and name to our widget, which in this case is a QTreeWidget. A particular effect may also have parameters, which are inserted in the tree as child nodes of their effect.

         Phonon::Effect *instance = new Phonon::Effect(effect, this);
         QList<Phonon::EffectParameter> parameters = instance->parameters();
         for (int i = 0; i < parameters.size(); ++i) {
                 Phonon::EffectParameter parameter = parameters.at(i);

             QVariant defaultValue = parameter.defaultValue();
             QVariant minimumValue = parameter.minimumValue();
             QVariant maximumValue = parameter.maximumValue();

             QString valueString = QString("%1 / %2 / %3")
                     .arg(defaultValue.toString()).arg(minimumValue.toString())
                     .arg(maximumValue.toString());

             QTreeWidgetItem *parameterItem = new QTreeWidgetItem(item);
             parameterItem->setText(0, tr("Parameter"));
             parameterItem->setText(1, parameter.name());
             parameterItem->setText(2, parameter.description());
             parameterItem->setText(3, QVariant::typeToName(parameter.type()));
             parameterItem->setText(4, valueString);
         }
     }

The parameters are only accessible through an instance of the Effect class. Notice that an effect is created with the effect description.

The EffectParameter contains information about one of an effects parameters. We pick out some of the information to describe the parameter in the tree widget.

 int main(int argv, char **args)
 {
     QApplication app(argv, args);
     app.setApplicationName("Phonon Capabilities Example");

     Window window;
     window.show();

     return app.exec();
 }