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 | |
31 | QT_BEGIN_HEADER |
32 | QT_BEGIN_NAMESPACE |
33 | |
34 | class QString; |
35 | |
36 | class AudioOutputAdaptor; |
37 | namespace 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 | |
176 | QT_END_NAMESPACE |
177 | QT_END_HEADER |
178 | |
179 | // vim: sw=4 ts=4 tw=80 |
180 | #endif // Phonon_AUDIOOUTPUT_H |
181 | |