1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : [email protected] 4 copyright : (C) 2006 by Urs Fleisch 5 email : [email protected] 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 description() 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 description \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