1 /*************************************************************************** 2 copyright : (C) 2011 by Mathias Panzenböck 3 email : [email protected] 4 ***************************************************************************/ 5 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. * 10 * * 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. * 15 * * 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., 51 Franklin Street, Fifth Floor, Boston, MA * 19 * 02110-1301 USA * 20 * * 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 ***************************************************************************/ 25 26 #ifndef TAGLIB_MODTAG_H 27 #define TAGLIB_MODTAG_H 28 29 #include "tag.h" 30 31 namespace TagLib { 32 33 namespace Mod { 34 35 /*! 36 * Tags for module files (Mod, S3M, IT, XM). 37 * 38 * Note that only the \a title is supported as such by most 39 * module file formats. Except for XM files the \a trackerName 40 * is derived from the file format or the flavour of the file 41 * format. For XM files it is stored in the file. 42 * 43 * The \a comment tag is not strictly supported by module files, 44 * but it is common practice to abuse instrument/sample/pattern 45 * names as multiline comments. TagLib does so as well. 46 */ 47 class TAGLIB_EXPORT Tag : public TagLib::Tag 48 { 49 public: 50 Tag(); 51 virtual ~Tag(); 52 53 /*! 54 * Returns the track name; if no track name is present in the tag 55 * String::null will be returned. 56 */ 57 virtual String title() const; 58 59 /*! 60 * Not supported by module files. Therefore always returns String::null. 61 */ 62 virtual String artist() const; 63 64 /*! 65 * Not supported by module files. Therefore always returns String::null. 66 */ 67 virtual String album() const; 68 69 /*! 70 * Returns the track comment derived from the instrument/sample/pattern 71 * names; if no comment is present in the tag String::null will be 72 * returned. 73 */ 74 virtual String comment() const; 75 76 /*! 77 * Not supported by module files. Therefore always returns String::null. 78 */ 79 virtual String genre() const; 80 81 /*! 82 * Not supported by module files. Therefore always returns 0. 83 */ 84 virtual unsigned int year() const; 85 86 /*! 87 * Not supported by module files. Therefore always returns 0. 88 */ 89 virtual unsigned int track() const; 90 91 /*! 92 * Returns the name of the tracker used to create/edit the module file. 93 * Only XM files store this tag to the file as such, for other formats 94 * (Mod, S3M, IT) this is derived from the file type or the flavour of 95 * the file type. Therefore only XM files might have an empty 96 * (String::null) tracker name. 97 */ 98 String trackerName() const; 99 100 /*! 101 * Sets the title to \a title. If \a title is String::null then this 102 * value will be cleared. 103 * 104 * The length limits per file type are (1 character = 1 byte): 105 * Mod 20 characters, S3M 27 characters, IT 25 characters and XM 20 106 * characters. 107 */ 108 virtual void setTitle(const String &title); 109 110 /*! 111 * Not supported by module files and therefore ignored. 112 */ 113 virtual void setArtist(const String &artist); 114 115 /*! 116 * Not supported by module files and therefore ignored. 117 */ 118 virtual void setAlbum(const String &album); 119 120 /*! 121 * Sets the comment to \a comment. If \a comment is String::null then 122 * this value will be cleared. 123 * 124 * Note that module file formats don't actually support a comment tag. 125 * Instead the names of instruments/patterns/samples are abused as 126 * a multiline comment. Because of this the number of lines in a 127 * module file is fixed to the number of instruments/patterns/samples. 128 * 129 * Also note that the instrument/pattern/sample name length is limited 130 * an thus the line length in comments are limited. Too big comments 131 * will be truncated. 132 * 133 * The line length limits per file type are (1 character = 1 byte): 134 * Mod 22 characters, S3M 27 characters, IT 25 characters and XM 22 135 * characters. 136 */ 137 virtual void setComment(const String &comment); 138 139 /*! 140 * Not supported by module files and therefore ignored. 141 */ 142 virtual void setGenre(const String &genre); 143 144 /*! 145 * Not supported by module files and therefore ignored. 146 */ 147 virtual void setYear(unsigned int year); 148 149 /*! 150 * Not supported by module files and therefore ignored. 151 */ 152 virtual void setTrack(unsigned int track); 153 154 /*! 155 * Sets the tracker name to \a trackerName. If \a trackerName is 156 * String::null then this value will be cleared. 157 * 158 * Note that only XM files support this tag. Setting the 159 * tracker name for other module file formats will be ignored. 160 * 161 * The length of this tag is limited to 20 characters (1 character 162 * = 1 byte). 163 */ 164 void setTrackerName(const String &trackerName); 165 166 /*! 167 * Implements the unified property interface -- export function. 168 * Since the module tag is very limited, the exported map is as well. 169 */ 170 PropertyMap properties() const; 171 172 /*! 173 * Implements the unified property interface -- import function. 174 * Because of the limitations of the module file tag, any tags besides 175 * COMMENT, TITLE and, if it is an XM file, TRACKERNAME, will be 176 * returned. Additionally, if the map contains tags with multiple values, 177 * all but the first will be contained in the returned map of unsupported 178 * properties. 179 */ 180 PropertyMap setProperties(const PropertyMap &); 181 182 private: 183 Tag(const Tag &); 184 Tag &operator=(const Tag &); 185 186 class TagPrivate; 187 TagPrivate *d; 188 }; 189 190 } 191 192 } 193 194 #endif 195