Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Controlling the Volume Widget

• Introduction
• Overview
• Example

Introduction

For devices that have physical volume keys, these can programatically be mapped by the applications need to show feedback in the form of a volume widget to the user. This is done by registering oneself with the Audio Volume Manager which is a service task that decides who currently has control of a displayable volume widget and the values it represents.

Overview

Some steps to be taken in interfacing with the Audio Volume Manager are shown below. An implemetation sourced from the greenphone will be provided as a concrete example after some generalities are presented.

1. Subclass QtopiaIpcAdaptor
2. register with the Audio Volume Manager by issuing a QCop message to registerHandler()
3. Implement the member functions:
   1. increaseVolume(int)
   2. decreaseVolume(int)

   These functions will be invoked as QCop messages by the Audio Volume Manager after a hardware Volume Key press. In order to report the modified volume back to the Audio Volume Manager the developer must issue a QCop message with signature currentVolume(QString) to the Audio Volume Manager

4. QCop messages setActiveDomain(QString name) and resetActiveDomain(QString name) hold and relinquish control respectively of handler name.
5. Unregister when control of the volume widget is no longer needed by issuing a QCop message to unregisterHandler()

Example

The greenphone provides an example where the device uses /dev/mixer to modify the master volume control of the soundcard. By registering itself with the Audio Volume Manager to gain control of volume hardware keys, it can display a volume widget to reflect this specific volume. The Audio Volume Manager writes this value into a QValueSpaceItem and the volume widget is updated accordingly.

Heres the header file for reference.

    class GreenphoneVolumeService : public QtopiaIpcAdaptor
    {
        Q_OBJECT
        enum AdjustType { Relative, Absolute };

    public:
        GreenphoneVolumeService();
        ~GreenphoneVolumeService();

    public slots:
        void increaseVolume(int increment);
        void decreaseVolume(int decrement);
        void setMute(bool mute);

    private slots:
        void registerService();
        void setCallDomain();

    private:
        void adjustVolume(int leftChannel, int rightChannel, AdjustType);

        int m_leftChannelVolume;
        int m_rightChannelVolume;

        GreenphoneVolumeServicePrivate *m_d;
    };

Important to note is that the relevant public slot functions correspond to QCop messages that are invoked by the Audio Volume Manager.

The registration:

    void GreenphoneVolumeService::registerService()
    {
        QtopiaIpcEnvelope   e("QPE/AudioVolumeManager", "registerHandler(QString,QString)");

        e << QString("Headset") << QString("QPE/AudioVolumeManager/GreenphoneVolumeService");

        QTimer::singleShot(0, this, SLOT(setCallDomain()));
    }

A similar QCop message should be used to unregister.

Taking a look at the implementation of the increaseVolume() function, we let the Audio Volume Manager know of the changed volume.

    void GreenphoneVolumeService::increaseVolume(int increment)
    {
        adjustVolume(increment, increment, Relative);
        m_d->sendCurrentVolume();
    }

Shown below is an implementation to report the modified volume back to the Audio Volume Manager.

    void sendCurrentVolume()
    {
            QString volume;
            volume.setNum(currVolume);
            QtopiaIpcEnvelope e("QPE/AudioVolumeManager","currentVolume(QString)");
            e << volume;
    }

Please see: $QTOPIA_DEPO_PATH/src/server/media/volumemanagement/audiovolumemanager.{h,cpp}. Note: returned volume values should be in the range 0-100.

server/media/genericvolumeservice is a generic implementation that uses QAudioMixer for the audio system adjustment. This is used by qvfb and could be used for a device by adding server/media/genericvolumeservice to the devices project.pri file. The c3200 device profile has been changed to use this.

Sometimes with alsa the auto-detect for the master volume can be incorrect. To override the auto-detect for the master volume control element and force use of a particular element set $HOME/Settings/Trolltech/Sound.conf [System] MasterName="PCM" MasterControl set to true allows the service to save and restore MasterVolume. If MasterControl is false (default) then current volume is used instead and volume is not saved to config.

See also QtopiaIpcAdaptor and QValueSpaceItem.