KCoreAddons

kaboutdata.h
1 /*
2  This file is part of the KDE Libraries
3 
4  SPDX-FileCopyrightText: 2000 Espen Sand <[email protected]>
5  SPDX-FileCopyrightText: 2008 Friedrich W. H. Kossebau <[email protected]>
6  SPDX-FileCopyrightText: 2010 Teo Mrnjavac <[email protected]>
7  SPDX-FileCopyrightText: 2013 David Faure <[email protected]>
8  SPDX-FileCopyrightText: 2017 Harald Sitter <[email protected]>
9 
10  SPDX-License-Identifier: LGPL-2.0-or-later
11 */
12 
13 #ifndef KABOUTDATA_H
14 #define KABOUTDATA_H
15 
16 #include <kcoreaddons_export.h>
17 #include <QString>
18 #include <QSharedDataPointer>
19 #include <QVariant>
20 #include <qcontainerfwd.h>
21 
22 class QCommandLineParser;
23 class QJsonObject;
24 class KAboutData;
25 class KPluginMetaData;
26 namespace KCrash
27 {
28 Q_DECL_IMPORT void defaultCrashHandler(int sig);
29 }
30 
55 class KCOREADDONS_EXPORT KAboutPerson
56 {
57  Q_GADGET
58  Q_PROPERTY(QString name READ name CONSTANT)
59  Q_PROPERTY(QString task READ task CONSTANT)
60  Q_PROPERTY(QString emailAddress READ emailAddress CONSTANT)
61  Q_PROPERTY(QString webAddress READ webAddress CONSTANT)
62  Q_PROPERTY(QString ocsUsername READ ocsUsername CONSTANT)
63  friend class KAboutData;
64 public:
80  explicit KAboutPerson(const QString &name = QString(),
81  const QString &task = QString(),
82  const QString &emailAddress = QString(),
83  const QString &webAddress = QString(),
84  const QString &ocsUsername = QString());
85 
90  KAboutPerson(const KAboutPerson &other);
91 
92  ~KAboutPerson();
93 
98  KAboutPerson &operator=(const KAboutPerson &other);
99 
105  QString name() const;
106 
112  QString task() const;
113 
119  QString emailAddress() const;
120 
126  QString webAddress() const;
127 
133  QString ocsUsername() const;
134 
150  static KAboutPerson fromJSON(const QJsonObject &obj);
151 
152 private:
156  explicit KAboutPerson(const QString &name, const QString &email, bool disambiguation);
157 
158  class Private;
159  Private *const d;
160 };
161 
172 class KCOREADDONS_EXPORT KAboutLicense
173 {
174  Q_GADGET
175  Q_PROPERTY(QString name READ name CONSTANT)
176  Q_PROPERTY(QString text READ text CONSTANT)
177  Q_PROPERTY(KAboutLicense::LicenseKey key READ key CONSTANT)
178  Q_PROPERTY(QString spdx READ spdx CONSTANT)
179  friend class KAboutData;
180 public:
181 
185  enum LicenseKey {
186  Custom = -2,
187  File = -1,
188  Unknown = 0,
189  GPL = 1,
190  GPL_V2 = 1,
191  LGPL = 2,
192  LGPL_V2 = 2,
193  BSDL = 3,
194  Artistic = 4,
195  QPL = 5,
196  QPL_V1_0 = 5,
197  GPL_V3 = 6,
198  LGPL_V3 = 7,
199  LGPL_V2_1 = 8
200  };
201  Q_ENUM(LicenseKey)
202 
203 
206  enum NameFormat {
207  ShortName,
208  FullName
209  };
210  Q_ENUM(NameFormat)
211 
212 
216  OnlyThisVersion,
217  OrLaterVersions
218  };
219  Q_ENUM(VersionRestriction)
220 
221 
224  explicit KAboutLicense();
225 
230  KAboutLicense(const KAboutLicense &other);
231 
232  ~KAboutLicense();
233 
238  KAboutLicense &operator=(const KAboutLicense &other);
239 
247  QString text() const;
248 
256  QString name(KAboutLicense::NameFormat formatName = ShortName) const;
257 
263  KAboutLicense::LicenseKey key() const;
264 
280  QString spdx() const;
281 
303  static KAboutLicense byKeyword(const QString &keyword);
304 
305 private:
309  explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType,
310  enum KAboutLicense::VersionRestriction versionRestriction,
311  const KAboutData *aboutData);
315  explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType, const KAboutData *aboutData);
319  explicit KAboutLicense(const KAboutData *aboutData);
323  void setLicenseFromPath(const QString &pathToFile);
327  void setLicenseFromText(const QString &licenseText);
328 
329  class Private;
331 };
332 
394 class KCOREADDONS_EXPORT KAboutData
395 {
396  Q_GADGET
397  Q_PROPERTY(QString displayName READ displayName CONSTANT)
398  Q_PROPERTY(QString productName READ productName CONSTANT)
399  Q_PROPERTY(QString componentName READ componentName CONSTANT)
400  Q_PROPERTY(QVariant programLogo READ programLogo CONSTANT)
401  Q_PROPERTY(QString shortDescription READ shortDescription CONSTANT)
402  Q_PROPERTY(QString homepage READ homepage CONSTANT)
403  Q_PROPERTY(QString bugAddress READ bugAddress CONSTANT)
404  Q_PROPERTY(QString version READ version CONSTANT)
405  Q_PROPERTY(QString otherText READ otherText CONSTANT)
406  Q_PROPERTY(QVariantList authors READ authorsVariant CONSTANT) //constant in practice as addAuthor is not exposed to Q_GADGET
407  Q_PROPERTY(QVariantList credits READ creditsVariant CONSTANT)
408  Q_PROPERTY(QVariantList translators READ translatorsVariant CONSTANT)
409  Q_PROPERTY(QVariantList licenses READ licensesVariant CONSTANT)
410  Q_PROPERTY(QString copyrightStatement READ copyrightStatement CONSTANT)
411  Q_PROPERTY(QString desktopFileName READ desktopFileName CONSTANT)
412 public:
413 
426  static KAboutData applicationData();
427 
444  static void setApplicationData(const KAboutData &aboutData);
445 
446 // BUILD, not ENABLE, as producers need to support the registry for backward-compat
447 #if KCOREADDONS_BUILD_DEPRECATED_SINCE(5, 76)
448 
456  KCOREADDONS_DEPRECATED_VERSION(5, 76, "See API docs")
457  static void registerPluginData(const KAboutData &aboutData);
458 #endif
459 
460 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 76)
461 
466  KCOREADDONS_DEPRECATED_VERSION(5, 76, "See API docs")
467  static KAboutData *pluginData(const QString &componentName);
468 #endif
469 
470 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 65)
471 
479  KCOREADDONS_DEPRECATED_VERSION(5, 65, "See API docs")
480  static KAboutData fromPluginMetaData(const KPluginMetaData &plugin);
481 #endif
482 
483 public:
532  // KF6: remove constructor that includes catalogName, and put default
533  // values back in for shortDescription and licenseType
534  KAboutData(const QString &componentName,
535  const QString &displayName,
536  const QString &version,
537  const QString &shortDescription,
538  enum KAboutLicense::LicenseKey licenseType,
539  const QString &copyrightStatement = QString(),
540  const QString &otherText = QString(),
541  const QString &homePageAddress = QString(),
542  const QString &bugAddress = QStringLiteral("[email protected]")
543  );
544 
563  explicit KAboutData(const QString &componentName = {},
564  const QString &displayName = {},
565  const QString &version = {}
566  );
567 
572  KAboutData(const KAboutData &other);
573 
578  KAboutData &operator=(const KAboutData &other);
579 
580  ~KAboutData();
581 
606  KAboutData &addAuthor(const QString &name,
607  const QString &task = QString(),
608  const QString &emailAddress = QString(),
609  const QString &webAddress = QString(),
610  const QString &ocsUsername = QString());
611 
635  KAboutData &addCredit(const QString &name,
636  const QString &task = QString(),
637  const QString &emailAddress = QString(),
638  const QString &webAddress = QString(),
639  const QString &ocsUsername = QString());
640 
662  KAboutData &setTranslator(const QString &name,
663  const QString &emailAddress);
664 
675  KAboutData &setLicenseText(const QString &license);
676 
691  KAboutData &addLicenseText(const QString &license);
692 
699  KAboutData &setLicenseTextFile(const QString &file);
700 
711  KAboutData &addLicenseTextFile(const QString &file);
712 
718  KAboutData &setComponentName(const QString &componentName);
719 
727  KAboutData &setDisplayName(const QString &displayName);
728 
729 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 2)
730 
742  KCOREADDONS_DEPRECATED_VERSION(5, 2, "Use QApplication::setWindowIcon")
743  KAboutData &setProgramIconName(const QString &iconName);
744 #endif
745 
760  KAboutData &setProgramLogo(const QVariant &image);
761 
774  KAboutData &setOcsProvider(const QString &providerUrl);
775 
781  KAboutData &setVersion(const QByteArray &version);
782 
790  KAboutData &setShortDescription(const QString &shortDescription);
791 
798  KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey);
799 
810  KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey,
811  KAboutLicense::VersionRestriction versionRestriction);
812 
822  KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey);
823 
837  KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey,
838  KAboutLicense::VersionRestriction versionRestriction);
839 
847  KAboutData &setCopyrightStatement(const QString &copyrightStatement);
848 
856  KAboutData &setOtherText(const QString &otherText);
857 
865  KAboutData &setHomepage(const QString &homepage);
866 
873  KAboutData &setBugAddress(const QByteArray &bugAddress);
874 
905  KAboutData &setOrganizationDomain(const QByteArray &domain);
906 
915  KAboutData &setProductName(const QByteArray &name);
916 
921  QString componentName() const;
922 
930  QString productName() const;
931 
936  QString displayName() const;
937 
943  QString organizationDomain() const;
944 
949  const char *internalProgramName() const;
950 
951 // Not using KCOREADDONS_ENABLE_DEPRECATED_SINCE because KXmlGui and KConfigWidgets need this, for compat
952 #if KCOREADDONS_BUILD_DEPRECATED_SINCE(5, 2)
953 
961  KCOREADDONS_DEPRECATED_VERSION(5, 2, "Use QApplication::windowIcon")
962  QString programIconName() const;
963 #endif
964 
974  QVariant programLogo() const;
975 
980  QString ocsProviderUrl() const;
981 
986  QString version() const;
987 
992  const char *internalVersion() const;
993 
999  QString shortDescription() const;
1000 
1006  QString homepage() const;
1007 
1012  QString bugAddress() const;
1013 
1018  const char *internalBugAddress() const;
1019 
1024  QList<KAboutPerson> authors() const;
1025 
1030  QList<KAboutPerson> credits() const;
1031 
1036  QList<KAboutPerson> translators() const;
1037 
1042  static QString aboutTranslationTeam();
1043 
1048  QString otherText() const;
1049 
1055  QList<KAboutLicense> licenses() const;
1056 
1061  QString copyrightStatement() const;
1062 
1070  QString customAuthorPlainText() const;
1071 
1079  QString customAuthorRichText() const;
1080 
1088  bool customAuthorTextEnabled() const;
1089 
1101  KAboutData &setCustomAuthorText(const QString &plainText,
1102  const QString &richText);
1103 
1109  KAboutData &unsetCustomAuthorText();
1110 
1125  bool setupCommandLine(QCommandLineParser *parser);
1126 
1133  void processCommandLine(QCommandLineParser *parser);
1134 
1163  KAboutData &setDesktopFileName(const QString &desktopFileName);
1164 
1170  QString desktopFileName() const;
1171 
1172 private:
1173  QVariantList licensesVariant() const;
1174  QVariantList authorsVariant() const;
1175  QVariantList creditsVariant() const;
1176  QVariantList translatorsVariant() const;
1177 
1178  friend void KCrash::defaultCrashHandler(int sig);
1179  static const KAboutData *applicationDataPointer();
1180 
1181  class Private;
1182  Private *const d;
1183 };
1184 
1185 Q_DECLARE_METATYPE(KAboutData)
1186 Q_DECLARE_METATYPE(KAboutLicense)
1187 Q_DECLARE_METATYPE(KAboutPerson)
1188 
1189 #endif
1190 
This class is used to store information about a license.
Definition: kaboutdata.h:172
KCRASH_EXPORT void defaultCrashHandler(int signal)
This class is used to store information about a program or plugin.
Definition: kaboutdata.h:394
LicenseKey
Describes the license of the software.
Definition: kaboutdata.h:185
This class is used to store information about a person or developer.
Definition: kaboutdata.h:55
NameFormat
Format of the license name.
Definition: kaboutdata.h:206
This class allows easily accessing some standardized values from the JSON metadata that can be embedd...
KAboutData & operator=(const KAboutData &other)
Assignment operator.
Definition: kaboutdata.cpp:584
VersionRestriction
Whether later versions of the license are allowed.
Definition: kaboutdata.h:215
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Fri Dec 4 2020 23:02:46 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.