1 /* BEGIN_COMMON_COPYRIGHT_HEADER 2 * (c)LGPL2+ 3 * 4 * LXQt - a lightweight, Qt based, desktop toolset 5 * https://lxqt.org 6 * 7 * Copyright: 2010-2011 Razor team 8 * Authors: 9 * Alexander Sokoloff <sokoloff.a@gmail.com> 10 * 11 * This program or library is free software; you can redistribute it 12 * and/or modify it under the terms of the GNU Lesser General Public 13 * License as published by the Free Software Foundation; either 14 * version 2.1 of the License, or (at your option) any later version. 15 * 16 * This library is distributed in the hope that it will be useful, 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 19 * Lesser General Public License for more details. 20 21 * You should have received a copy of the GNU Lesser General 22 * Public License along with this library; if not, write to the 23 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 24 * Boston, MA 02110-1301 USA 25 * 26 * END_COMMON_COPYRIGHT_HEADER */ 27 28 #ifndef QTXDG_XDGDESKTOPFILE_H 29 #define QTXDG_XDGDESKTOPFILE_H 30 31 #include <QSharedDataPointer> 32 #include <QString> 33 #include <QVariant> 34 #include <QStringList> 35 #include <QtGui/QIcon> 36 #include <QSettings> 37 38 class XdgDesktopFileData; 39 enum UserDirectory 40 { 41 Desktop, 42 Download, 43 Templates, 44 PublicShare, 45 Documents, 46 Music, 47 Pictures, 48 Videos 49 }; 50 /** 51 \brief Desktop files handling. 52 XdgDesktopFile class gives the interface for reading the values from the XDG .desktop file. 53 The interface of this class is similar on QSettings. XdgDesktopFile objects can be passed 54 around by value since the XdgDesktopFile class uses implicit data sharing. 55 56 The Desktop Entry Specification defines 3 types of desktop entries: Application, Link and 57 Directory. The format of .desktop file is described on 58 http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html 59 60 Note that not all methods in this class make sense for all types of desktop files. 61 \author Alexander Sokoloff <sokoloff.a@gmail.com> 62 */ 63 64 class XdgDesktopFile 65 { 66 public: 67 /*! The Desktop Entry Specification defines 3 types of desktop entries: Application, Link and 68 Directory. File type is determined by the "Type" tag. */ 69 enum Type 70 { 71 UnknownType, //! Unknown desktop file type. Maybe is invalid. 72 ApplicationType, //! The file describes application. 73 LinkType, //! The file describes URL. 74 DirectoryType //! The file describes directory settings. 75 }; 76 77 //! Constructs an empty XdgDesktopFile 78 XdgDesktopFile(); 79 80 /*! Constructs a copy of other. 81 This operation takes constant time, because XdgDesktopFile is implicitly shared. This makes 82 returning a XdgDesktopFile from a function very fast. If a shared instance is modified, 83 it will be copied (copy-on-write), and that takes linear time. */ 84 XdgDesktopFile(const XdgDesktopFile& other); 85 86 /*! Constructs a new basic DesktopFile. If type is: 87 - ApplicationType, "value" should be the Exec value; 88 - LinkType, "value" should be the URL; 89 - DirectoryType, "value" should be omitted */ 90 XdgDesktopFile(XdgDesktopFile::Type type, const QString& name, const QString& value = QString()); 91 92 //! Destroys the object. 93 virtual ~XdgDesktopFile(); 94 95 //! Loads an DesktopFile from the file with the given fileName. 96 virtual bool load(const QString& fileName); 97 98 /*! Returns the value for key. If the key doesn't exist, returns defaultValue. 99 If no default value is specified, a default QVariant is returned. */ 100 QVariant value(const QString& key, const QVariant& defaultValue = QVariant()) const; 101 102 /*! Returns the localized value for key. In the desktop file keys may be postfixed by [LOCALE]. If the 103 localized value doesn't exist, returns non lokalized value. If non localized value doesn't exist, returns defaultValue. 104 LOCALE must be of the form lang_COUNTRY.ENCODING@MODIFIER, where _COUNTRY, .ENCODING, and @MODIFIER may be omitted. 105 106 If no default value is specified, a default QVariant is returned. */ 107 QVariant localizedValue(const QString& key, const QVariant& defaultValue = QVariant()) const; 108 109 //! Returns true if there exists a setting called key; returns false otherwise. 110 bool contains(const QString& key) const; 111 112 //! Returns true if the XdgDesktopFile is valid; otherwise returns false. 113 bool isValid() const; 114 115 static QIcon fromTheme(const QString& iconName, int size, const QIcon& fallback = QIcon()); 116 //! Returns an icon specified in this file. 117 QIcon const icon(int size, const QIcon& fallback = QIcon()) const; 118 119 //! This function is provided for convenience. It's equivalent to calling localizedValue("Name").toString(). name()120 QString name() const { return localizedValue(QLatin1String("Name")).toString(); } 121 122 /*! Returns the desktop file type. 123 @see XdgDesktopFile::Type */ 124 Type type() const; 125 126 /*! For file with Application type. Starts the program with the optional urls in a new process, and detaches from it. 127 Returns true on success; otherwise returns false. 128 @par urls - A list of files or URLS. Each file is passed as a separate argument to the executable program. 129 130 For file with Link type. Opens URL in the associated application. Parametr urls is not used. 131 132 For file with Directory type, do nothing. */ 133 bool startDetached(const QStringList& urls) const; 134 135 //! This function is provided for convenience. It's equivalent to calling startDetached(QStringList(url)). 136 bool startDetached(const QString& url = QString()) const; 137 138 /*! A Exec value consists of an executable program optionally followed by one or more arguments. 139 This function expands this arguments and returns command line string parts. 140 Note this method make sense only for Application type. 141 @par urls - A list of files or URLS. Each file is passed as a separate argument to the result string program.*/ 142 QStringList expandExecString(const QStringList& urls = QStringList()) const; 143 144 protected: prefix()145 virtual QString prefix() const { return QLatin1String("Desktop Entry"); } check()146 virtual bool check() const { return true; } 147 private: 148 /*! Returns the localized version of the key if the Desktop File already contains a localized version of it. 149 If not, returns the same key back */ 150 QString localizedKey(const QString& key) const; 151 152 QSharedDataPointer<XdgDesktopFileData> d; 153 }; 154 155 156 /// Synonym for QList<XdgDesktopFile> 157 typedef QList<XdgDesktopFile> XdgDesktopFileList; 158 159 #endif // QTXDG_XDGDESKTOPFILE_H 160