KContacts

sound.h
1 /*
2  This file is part of the KContacts framework.
3  SPDX-FileCopyrightText: 2002 Tobias Koenig <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KCONTACTS_SOUND_H
9 #define KCONTACTS_SOUND_H
10 
11 #include "kcontacts_export.h"
12 #include <QSharedDataPointer>
13 #include <QString>
14 
15 namespace KContacts
16 {
17 /** @short Class that holds a Sound clip for a contact.
18  *
19  * The sound can be played doing something like this:
20  *
21  * \code
22  * KTempFile tmp;
23  * if ( sound.isIntern() ) {
24  * tmp.file()->write( sound.data() );
25  * tmp.close();
26  * KAudioPlayer::play( tmp.name() );
27  * } else if( !sound.url().isEmpty() ) {
28  * QString tmpFile;
29  * if ( !KIO::NetAccess::download( QUrl( themeURL.url() ), tmpFile, 0 ) ) {
30  * KMessageBox::error( 0,
31  * KIO::NetAccess::lastErrorString(),
32  * i18n( "Failed to download sound file" ),
33  * KMessageBox::Notify
34  * );
35  * return;
36  * }
37  * KAudioPlayer::play( tmpFile );
38  * }
39  * \endcode
40  *
41  * Unfortunately, KAudioPlayer::play is ASync, so to delete the temporary file
42  * the best you can really do is set a timer.
43  *
44  */
45 class KCONTACTS_EXPORT Sound
46 {
47  friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Sound &);
48  friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Sound &);
49 
50 public:
51  /**
52  * Creates an empty sound object.
53  */
54  Sound();
55 
56  /**
57  * Creates a sound object for the given url.
58  *
59  * @param url A url that describes the position of the sound file.
60  */
61  Sound(const QString &url);
62 
63  /**
64  * Creates a sound object for the given data.
65  *
66  * @param data The raw data of the sound.
67  */
68  Sound(const QByteArray &data);
69 
70  /**
71  * Copy constructor.
72  */
73  Sound(const Sound &other);
74 
75  /**
76  * Destroys the sound object.
77  */
78  ~Sound();
79 
80  typedef QVector<Sound> List;
81  /**
82  * Assignment operator.
83  *
84  * @param other The sound object to assign to @c this
85  */
86  Sound &operator=(const Sound &other);
87 
88  /**
89  * Equality operator.
90  *
91  * @param other The object to compare with
92  *
93  * @return @c true if the two objects are equal, otherwise @c false
94  */
95  Q_REQUIRED_RESULT bool operator==(const Sound &other) const;
96 
97  /**
98  * Not-Equal operator.
99  *
100  * @param other The object to compare with
101  *
102  * @return @c true if the two objects are not equal, otherwise @c false
103  */
104  Q_REQUIRED_RESULT bool operator!=(const Sound &other) const;
105 
106  /**
107  * Sets a URL for the location of the sound file. When using this
108  * function, isIntern() will return 'false' until you use
109  * setData().
110  *
111  * @param url The location URL of the sound file.
112  */
113  void setUrl(const QString &url);
114 
115  /**
116  * Returns true, if the sound object is empty.
117  */
118  Q_REQUIRED_RESULT bool isEmpty() const;
119 
120  /**
121  * Sets the raw data of the sound. When using this function,
122  * isIntern() will return 'true' until you use setUrl().
123  *
124  * @param data The raw data of the sound.
125  */
126  void setData(const QByteArray &data);
127 
128  /**
129  * Returns whether the sound is described by a URL (extern) or
130  * by the raw data (intern).
131  * When this method returns 'true' you can use data() to
132  * get the raw data. Otherwise you can request the URL of this
133  * sound by url() and load the raw data from that location.
134  */
135  Q_REQUIRED_RESULT bool isIntern() const;
136 
137  /**
138  * Returns the location URL of this sound.
139  */
140  Q_REQUIRED_RESULT QString url() const;
141 
142  /**
143  * Returns the raw data of this sound.
144  */
145  Q_REQUIRED_RESULT QByteArray data() const;
146 
147  /**
148  * Returns string representation of the sound.
149  */
150  Q_REQUIRED_RESULT QString toString() const;
151 
152 private:
153  class Private;
155 };
156 
157 /**
158  * Serializes the @p sound object into the @p stream.
159  */
160 KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Sound &sound);
161 
162 /**
163  * Initializes the @p sound object from the @p stream.
164  */
165 KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Sound &sound);
166 }
167 Q_DECLARE_TYPEINFO(KContacts::Sound, Q_MOVABLE_TYPE);
168 #endif
QDataStream & operator>>(QDataStream &in, KDateTime::Spec &spec)
QDataStream & operator<<(QDataStream &out, const KDateTime::Spec &spec)
Class that holds a Sound clip for a contact.
Definition: sound.h:45
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Jun 12 2021 22:55:11 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.