Phonon

audiooutput.h
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
32class QString;
33
34class AudioOutputAdaptor;
35namespace Phonon
36{
37 class AudioOutputPrivate;
38
39 /** \class AudioOutput audiooutput.h phonon/AudioOutput
40 * \short Class for audio output to the soundcard.
41 *
42 * Use this class to define the audio output.
43 *
44 * \ingroup Frontend
45 * \author Matthias Kretz <kretz@kde.org>
46 * \see Phonon::Ui::VolumeSlider
47 */
48 class PHONON_EXPORT AudioOutput : public AbstractAudioOutput
49 {
50 friend class FactoryPrivate;
51 friend class ::AudioOutputAdaptor;
52 Q_OBJECT
53 P_DECLARE_PRIVATE(AudioOutput)
54 /**
55 * This is the name that appears in Mixer applications that control
56 * the volume of this output.
57 *
58 * \see category
59 */
60 Q_PROPERTY(QString name READ name WRITE setName)
61 /**
62 * This is the current loudness of the output (it is using Stevens' law
63 * to calculate the change in voltage internally).
64 *
65 * \see volumeDecibel
66 */
67 Q_PROPERTY(qreal volume READ volume WRITE setVolume NOTIFY volumeChanged)
68 /**
69 * This is the current volume of the output in decibel.
70 *
71 * 0 dB means no change in volume, -6dB means an attenuation of the
72 * voltage to 50% and an attenuation of the power to 25%, -inf dB means
73 * silence.
74 *
75 * \see volume
76 */
77 Q_PROPERTY(qreal volumeDecibel READ volumeDecibel WRITE setVolumeDecibel)
78 /**
79 * This property holds the (hardware) destination for the output.
80 *
81 * The default device is determined by the category and the global
82 * configuration for that category of outputs. Normally you don't need
83 * to override this setting - letting the user change the global
84 * configuration is the right choice. You can still override the
85 * device though, if you have good reasons to do so.
86 *
87 * \see outputDeviceChanged
88 */
89 Q_PROPERTY(AudioOutputDevice outputDevice READ outputDevice WRITE setOutputDevice)
90
91 /**
92 * This property tells whether the output is muted.
93 *
94 * Muting the output has the same effect as calling setVolume(0.0).
95 */
96 Q_PROPERTY(bool muted READ isMuted WRITE setMuted NOTIFY mutedChanged)
97 public:
98 /**
99 * Creates a new AudioOutput that defines output to a physical
100 * device.
101 *
102 * \param category The category can be used by mixer applications to group volume
103 * controls of applications into categories. That makes it easier for
104 * the user to identify the programs.
105 * The category is also used for the default output device that is
106 * configured centrally. As an example: often users want to have the
107 * audio signal of a VoIP application go to their USB headset while
108 * all other sounds should go to the internal soundcard.
109 *
110 * \param parent QObject parent
111 *
112 * \see Phonon::categoryToString
113 * \see outputDevice
114 */
115 explicit AudioOutput(Phonon::Category category, QObject *parent = nullptr);
116 explicit AudioOutput(QObject *parent = nullptr);
117
118 QString name() const;
119 qreal volume() const;
120 qreal volumeDecibel() const;
121
122 /**
123 * Returns the category of this output.
124 *
125 * \see AudioOutput(Phonon::Category, QObject *)
126 */
127 Phonon::Category category() const;
128 AudioOutputDevice outputDevice() const;
129 bool isMuted() const;
130
131 public Q_SLOTS:
132 void setName(const QString &newName);
133 void setVolume(qreal newVolume);
134 void setVolumeDecibel(qreal newVolumeDecibel);
135 bool setOutputDevice(const Phonon::AudioOutputDevice &newAudioOutputDevice);
136 void setMuted(bool mute);
137
138 Q_SIGNALS:
139 /**
140 * This signal is emitted whenever the volume has changed. As the
141 * volume can change without a call to setVolume this is important
142 * to keep a widget showing the current volume up to date.
143 */
144 void volumeChanged(qreal newVolume);
145
146 /**
147 * This signal is emitted when the muted property has changed. As
148 * this property can change by outside sources, a UI element showing
149 * the muted property should listen to this signal.
150 */
151 void mutedChanged(bool);
152
153 /**
154 * This signal is emitted when the (hardware) device for the output
155 * has changed.
156 *
157 * The change can happen either through setOutputDevice or if the
158 * global configuration for the used category has changed.
159 *
160 * \see outputDevice
161 */
162 void outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice);
163
164 private:
165 Q_PRIVATE_SLOT(k_func(), void _k_volumeChanged(qreal))
166 Q_PRIVATE_SLOT(k_func(), void _k_mutedChanged(bool))
167 Q_PRIVATE_SLOT(k_func(), void _k_revertFallback())
168 Q_PRIVATE_SLOT(k_func(), void _k_audioDeviceFailed())
169 Q_PRIVATE_SLOT(k_func(), void _k_deviceListChanged())
170 Q_PRIVATE_SLOT(k_func(), void _k_deviceChanged(int device))
171 };
172} //namespace Phonon
173
174
175// vim: sw=4 ts=4 tw=80
176#endif // Phonon_AUDIOOUTPUT_H
Common base class for all audio outputs.
Class for audio output to the soundcard.
Definition audiooutput.h:49
Provides a tuple of enduser visible name and description.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:20:24 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.