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 | |
33 | namespace 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 | (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 | |