1/* This file is part of the KDE project
2 Copyright (C) 2005-2006 Matthias Kretz <kretz@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), Nokia Corporation
10 (or its successors, if any) and the KDE Free Qt Foundation, which shall
11 act as a proxy defined in Section 6 of version 3 of the license.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library. If not, see <http://www.gnu.org/licenses/>.
20
21*/
22#ifndef Phonon_AUDIOOUTPUT_H
23#define Phonon_AUDIOOUTPUT_H
24
25#include "phonon_export.h"
26#include "abstractaudiooutput.h"
27#include "phonondefs.h"
28#include "phononnamespace.h"
29#include "objectdescription.h"
30
31QT_BEGIN_HEADER
32QT_BEGIN_NAMESPACE
33
34class QString;
35
36class AudioOutputAdaptor;
37namespace Phonon
38{
39 class AudioOutputPrivate;
40
41 /** \class AudioOutput audiooutput.h Phonon/AudioOutput
42 * \short Class for audio output to the soundcard.
43 *
44 * Use this class to define the audio output.
45 *
46 * \ingroup Frontend
47 * \author Matthias Kretz <kretz@kde.org>
48 * \see Phonon::Ui::VolumeSlider
49 */
50 class PHONON_EXPORT AudioOutput : public AbstractAudioOutput
51 {
52 friend class FactoryPrivate;
53 friend class ::AudioOutputAdaptor;
54 Q_OBJECT
55 K_DECLARE_PRIVATE(AudioOutput)
56 /**
57 * This is the name that appears in Mixer applications that control
58 * the volume of this output.
59 *
60 * \see category
61 */
62 Q_PROPERTY(QString name READ name WRITE setName)
63 /**
64 * This is the current loudness of the output (it is using Stevens' law
65 * to calculate the change in voltage internally).
66 *
67 * \see volumeDecibel
68 */
69 Q_PROPERTY(qreal volume READ volume WRITE setVolume NOTIFY volumeChanged)
70 /**
71 * This is the current volume of the output in decibel.
72 *
73 * 0 dB means no change in volume, -6dB means an attenuation of the
74 * voltage to 50% and an attenuation of the power to 25%, -inf dB means
75 * silence.
76 *
77 * \see volume
78 */
79 Q_PROPERTY(qreal volumeDecibel READ volumeDecibel WRITE setVolumeDecibel)
80 /**
81 * This property holds the (hardware) destination for the output.
82 *
83 * The default device is determined by the category and the global
84 * configuration for that category of outputs. Normally you don't need
85 * to override this setting - letting the user change the global
86 * configuration is the right choice. You can still override the
87 * device though, if you have good reasons to do so.
88 *
89 * \see outputDeviceChanged
90 */
91 Q_PROPERTY(AudioOutputDevice outputDevice READ outputDevice WRITE setOutputDevice)
92
93 /**
94 * This property tells whether the output is muted.
95 *
96 * Muting the output has the same effect as calling setVolume(0.0).
97 */
98 Q_PROPERTY(bool muted READ isMuted WRITE setMuted NOTIFY mutedChanged)
99 public:
100 /**
101 * Creates a new AudioOutput that defines output to a physical
102 * device.
103 *
104 * \param category The category can be used by mixer applications to group volume
105 * controls of applications into categories. That makes it easier for
106 * the user to identify the programs.
107 * The category is also used for the default output device that is
108 * configured centrally. As an example: often users want to have the
109 * audio signal of a VoIP application go to their USB headset while
110 * all other sounds should go to the internal soundcard.
111 *
112 * \param parent QObject parent
113 *
114 * \see Phonon::categoryToString
115 * \see outputDevice
116 */
117 explicit AudioOutput(Phonon::Category category, QObject *parent = 0);
118 explicit AudioOutput(QObject *parent = 0);
119
120 QString name() const;
121 qreal volume() const;
122 qreal volumeDecibel() const;
123
124 /**
125 * Returns the category of this output.
126 *
127 * \see AudioOutput(Phonon::Category, QObject *)
128 */
129 Phonon::Category category() const;
130 AudioOutputDevice outputDevice() const;
131 bool isMuted() const;
132
133 public Q_SLOTS:
134 void setName(const QString &newName);
135 void setVolume(qreal newVolume);
136 void setVolumeDecibel(qreal newVolumeDecibel);
137 bool setOutputDevice(const Phonon::AudioOutputDevice &newAudioOutputDevice);
138 void setMuted(bool mute);
139
140 Q_SIGNALS:
141 /**
142 * This signal is emitted whenever the volume has changed. As the
143 * volume can change without a call to setVolume (calls over dbus)
144 * this is important
145 * to keep a widget showing the current volume up to date.
146 */
147 void volumeChanged(qreal newVolume);
148
149 /**
150 * This signal is emitted when the muted property has changed. As
151 * this property can change by IPC (DBus) calls a UI element showing
152 * the muted property should listen to this signal.
153 */
154 void mutedChanged(bool);
155
156 /**
157 * This signal is emitted when the (hardware) device for the output
158 * has changed.
159 *
160 * The change can happen either through setOutputDevice or if the
161 * global configuration for the used category has changed.
162 *
163 * \see outputDevice
164 */
165 void outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice);
166
167 private:
168 Q_PRIVATE_SLOT(k_func(), void _k_volumeChanged(qreal))
169 Q_PRIVATE_SLOT(k_func(), void _k_revertFallback())
170 Q_PRIVATE_SLOT(k_func(), void _k_audioDeviceFailed())
171 Q_PRIVATE_SLOT(k_func(), void _k_deviceListChanged())
172 Q_PRIVATE_SLOT(k_func(), void _k_deviceChanged(QString streamUuid, int device))
173 };
174} //namespace Phonon
175
176QT_END_NAMESPACE
177QT_END_HEADER
178
179// vim: sw=4 ts=4 tw=80
180#endif // Phonon_AUDIOOUTPUT_H
181