1/***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 copyright : (C) 2006 by Urs Fleisch
5 email : ufleisch@users.sourceforge.net
6 ***************************************************************************/
7
8/***************************************************************************
9 * This library is free software; you can redistribute it and/or modify *
10 * it under the terms of the GNU Lesser General Public License version *
11 * 2.1 as published by the Free Software Foundation. *
12 * *
13 * This library is distributed in the hope that it will be useful, but *
14 * 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, write to the Free Software *
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA *
21 * 02110-1301 USA *
22 * *
23 * Alternatively, this file is available under the Mozilla Public *
24 * License Version 1.1. You may obtain a copy of the License at *
25 * http://www.mozilla.org/MPL/ *
26 ***************************************************************************/
27
28#ifndef TAGLIB_UNSYNCHRONIZEDLYRICSFRAME_H
29#define TAGLIB_UNSYNCHRONIZEDLYRICSFRAME_H
30
31#include "id3v2frame.h"
32
33namespace TagLib {
34
35 namespace ID3v2 {
36
37 //! ID3v2 unsynchronized lyrics frame
38 /*!
39 * An implementation of ID3v2 unsynchronized lyrics.
40 */
41 class TAGLIB_EXPORT UnsynchronizedLyricsFrame : public Frame
42 {
43 friend class FrameFactory;
44
45 public:
46 /*!
47 * Construct an empty unsynchronized lyrics frame that will use the text encoding
48 * \a encoding.
49 */
50 explicit UnsynchronizedLyricsFrame(String::Type encoding = String::Latin1);
51
52 /*!
53 * Construct a unsynchronized lyrics frame based on the data in \a data.
54 */
55 explicit UnsynchronizedLyricsFrame(const ByteVector &data);
56
57 /*!
58 * Destroys this UnsynchronizedLyricsFrame instance.
59 */
60 virtual ~UnsynchronizedLyricsFrame();
61
62 /*!
63 * Returns the text of this unsynchronized lyrics frame.
64 *
65 * \see text()
66 */
67 virtual String toString() const;
68
69 /*!
70 * Returns the language encoding as a 3 byte encoding as specified by
71 * <a href="http://en.wikipedia.org/wiki/ISO_639">ISO-639-2</a>.
72 *
73 * \note Most taggers simply ignore this value.
74 *
75 * \see setLanguage()
76 */
77 ByteVector language() const;
78
79 /*!
80 * Returns the description of this unsynchronized lyrics frame.
81 *
82 * \note Most taggers simply ignore this value.
83 *
84 * \see setDescription()
85 */
86 String description() const;
87
88 /*!
89 * Returns the text of this unsynchronized lyrics frame.
90 *
91 * \see setText()
92 */
93 String text() const;
94
95 /*!
96 * Set the language using the 3 byte language code from
97 * <a href="http://en.wikipedia.org/wiki/ISO_639">ISO-639-2</a> to
98 * \a languageCode.
99 *
100 * \see language()
101 */
102 void setLanguage(const ByteVector &languageCode);
103
104 /*!
105 * Sets the description of the unsynchronized lyrics frame to \a s.
106 *
107 * \see decription()
108 */
109 void setDescription(const String &s);
110
111 /*!
112 * Sets the text portion of the unsynchronized lyrics frame to \a s.
113 *
114 * \see text()
115 */
116 virtual void setText(const String &s);
117
118 /*!
119 * Returns the text encoding that will be used in rendering this frame.
120 * This defaults to the type that was either specified in the constructor
121 * or read from the frame when parsed.
122 *
123 * \see setTextEncoding()
124 * \see render()
125 */
126 String::Type textEncoding() const;
127
128 /*!
129 * Sets the text encoding to be used when rendering this frame to
130 * \a encoding.
131 *
132 * \see textEncoding()
133 * \see render()
134 */
135 void setTextEncoding(String::Type encoding);
136
137
138 /*! Parses this frame as PropertyMap with a single key.
139 * - if description() is empty or "LYRICS", the key will be "LYRICS"
140 * - if description() is not a valid PropertyMap key, the frame will be
141 * marked unsupported by an entry "USLT/<description>" in the unsupportedData()
142 * attribute of the returned map.
143 * - otherwise, the key will be "LYRICS:<description>"
144 * - The single value will be the frame's text().
145 * Note that currently the language() field is not supported by the PropertyMap
146 * interface.
147 */
148 PropertyMap asProperties() const;
149
150 /*!
151 * LyricsFrames each have a unique description. This searches for a lyrics
152 * frame with the decription \a d and returns a pointer to it. If no
153 * frame is found that matches the given description null is returned.
154 *
155 * \see description()
156 */
157 static UnsynchronizedLyricsFrame *findByDescription(const Tag *tag, const String &d);
158
159 protected:
160 // Reimplementations.
161
162 virtual void parseFields(const ByteVector &data);
163 virtual ByteVector renderFields() const;
164
165 private:
166 /*!
167 * The constructor used by the FrameFactory.
168 */
169 UnsynchronizedLyricsFrame(const ByteVector &data, Header *h);
170 UnsynchronizedLyricsFrame(const UnsynchronizedLyricsFrame &);
171 UnsynchronizedLyricsFrame &operator=(const UnsynchronizedLyricsFrame &);
172
173 class UnsynchronizedLyricsFramePrivate;
174 UnsynchronizedLyricsFramePrivate *d;
175 };
176
177 }
178}
179#endif
180