1 /***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
6 /***************************************************************************
7 * This library is free software; you can redistribute it and/or modify *
8 * it under the terms of the GNU Lesser General Public License version *
9 * 2.1 as published by the Free Software Foundation. *
11 * This library is distributed in the hope that it will be useful, but *
12 * WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the Free Software *
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
21 * Alternatively, this file is available under the Mozilla Public *
22 * License Version 1.1. You may obtain a copy of the License at *
23 * http://www.mozilla.org/MPL/ *
24 ***************************************************************************/
26 #ifndef TAGLIB_COMMENTSFRAME_H
27 #define TAGLIB_COMMENTSFRAME_H
29 #include "id3v2frame.h"
30 #include "taglib_export.h"
36 //! An implementation of ID3v2 comments
39 * This implements the ID3v2 comment format. An ID3v2 comment concists of
40 * a language encoding, a description and a single text field.
43 class TAGLIB_EXPORT CommentsFrame : public Frame
45 friend class FrameFactory;
49 * Construct an empty comment frame that will use the text encoding
52 explicit CommentsFrame(String::Type encoding = String::Latin1);
55 * Construct a comment based on the data in \a data.
57 explicit CommentsFrame(const ByteVector &data);
60 * Destroys this CommentFrame instance.
62 virtual ~CommentsFrame();
65 * Returns the text of this comment.
69 virtual String toString() const;
72 * Returns the language encoding as a 3 byte encoding as specified by
73 * <a href="http://en.wikipedia.org/wiki/ISO_639">ISO-639-2</a>.
75 * \note Most taggers simply ignore this value.
79 ByteVector language() const;
82 * Returns the description of this comment.
84 * \note Most taggers simply ignore this value.
86 * \see setDescription()
88 String description() const;
91 * Returns the text of this comment.
98 * Set the language using the 3 byte language code from
99 * <a href="http://en.wikipedia.org/wiki/ISO_639">ISO-639-2</a> to
104 void setLanguage(const ByteVector &languageCode);
107 * Sets the description of the comment to \a s.
111 void setDescription(const String &s);
114 * Sets the text portion of the comment to \a s.
118 virtual void setText(const String &s);
121 * Returns the text encoding that will be used in rendering this frame.
122 * This defaults to the type that was either specified in the constructor
123 * or read from the frame when parsed.
125 * \see setTextEncoding()
128 String::Type textEncoding() const;
131 * Sets the text encoding to be used when rendering this frame to
134 * \see textEncoding()
137 void setTextEncoding(String::Type encoding);
140 * Comments each have a unique description. This searches for a comment
141 * frame with the decription \a d and returns a pointer to it. If no
142 * frame is found that matches the given description null is returned.
146 static CommentsFrame *findByDescription(const Tag *tag, const String &d);
149 // Reimplementations.
151 virtual void parseFields(const ByteVector &data);
152 virtual ByteVector renderFields() const;
156 * The constructor used by the FrameFactory.
158 CommentsFrame(const ByteVector &data, Header *h);
159 CommentsFrame(const CommentsFrame &);
160 CommentsFrame &operator=(const CommentsFrame &);
162 class CommentsFramePrivate;
163 CommentsFramePrivate *d;