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  SPDX-FileCopyrightText: 2021 Julius K├╝nzel <[email protected]>
10 
11  SPDX-License-Identifier: LGPL-2.0-or-later
12 */
13 
14 #ifndef KABOUTDATA_H
15 #define KABOUTDATA_H
16 
17 #include <QSharedDataPointer>
18 #include <QString>
19 #include <QVariant>
20 #include <kcoreaddons_export.h>
21 #include <memory>
22 #include <qcontainerfwd.h>
23 
24 class QCommandLineParser;
25 class QJsonObject;
26 class KAboutData;
27 class KPluginMetaData;
28 namespace KCrash
29 {
30 #ifdef KCOREADDONS_STATIC
31 void defaultCrashHandler(int sig);
32 #else
33 Q_DECL_IMPORT void defaultCrashHandler(int sig);
34 #endif
35 }
36 
37 /**
38  * This class is used to store information about a person or developer.
39  * It can store the person's name, a task, an email address and a
40  * link to a home page. This class is intended for use in the
41  * KAboutData class, but it can be used elsewhere as well.
42  * Normally you should at least define the person's name.
43  * Creating a KAboutPerson object by yourself is relatively useless,
44  * but the KAboutData methods KAboutData::authors() and KAboutData::credits()
45  * return lists of KAboutPerson data objects which you can examine.
46  *
47  * Example usage within a main(), retrieving the list of people involved
48  * with a program and re-using data from one of them:
49  *
50  * @code
51  * KAboutData about("khello", i18n("KHello"), "0.1",
52  * i18n("A KDE version of Hello, world!"),
53  * KAboutLicense::LGPL,
54  * i18n("Copyright (C) 2014 Developer"));
55  *
56  * about.addAuthor(i18n("Joe Developer"), i18n("developer"), "[email protected]", 0);
57  * QList<KAboutPerson> people = about.authors();
58  * about.addCredit(people[0].name(), people[0].task());
59  * @endcode
60  */
61 class KCOREADDONS_EXPORT KAboutPerson
62 {
63  Q_GADGET
64  Q_PROPERTY(QString name READ name CONSTANT)
65  Q_PROPERTY(QString task READ task CONSTANT)
66  Q_PROPERTY(QString emailAddress READ emailAddress CONSTANT)
67  Q_PROPERTY(QString webAddress READ webAddress CONSTANT)
68  Q_PROPERTY(QString ocsUsername READ ocsUsername CONSTANT)
69  friend class KAboutData;
70  friend class KAboutDataPrivate;
71 
72 public:
73  /**
74  * Convenience constructor
75  *
76  * @param name The name of the person.
77  *
78  * @param task The task of this person.
79  *
80  * @param emailAddress The email address of the person.
81  *
82  * @param webAddress Home page of the person.
83  *
84  * @param ocsUsername Open Collaboration Services username of the person.
85  *
86  * @p name default argument @since 5.53
87  */
88  explicit KAboutPerson(const QString &name = QString(),
89  const QString &task = QString(),
90  const QString &emailAddress = QString(),
91  const QString &webAddress = QString(),
92  const QString &ocsUsername = QString());
93 
94  /**
95  * Copy constructor. Performs a deep copy.
96  * @param other object to copy
97  */
98  KAboutPerson(const KAboutPerson &other);
99 
100  ~KAboutPerson();
101 
102  /**
103  * Assignment operator. Performs a deep copy.
104  * @param other object to copy
105  */
106  KAboutPerson &operator=(const KAboutPerson &other);
107 
108  /**
109  * The person's name
110  * @return the person's name (can be QString(), if it has been
111  * constructed with an empty name)
112  */
113  QString name() const;
114 
115  /**
116  * The person's task
117  * @return the person's task (can be QString(), if it has been
118  * constructed with an empty task)
119  */
120  QString task() const;
121 
122  /**
123  * The person's email address
124  * @return the person's email address (can be QString(), if it has been
125  * constructed with an empty email)
126  */
127  QString emailAddress() const;
128 
129  /**
130  * The home page or a relevant link
131  * @return the persons home page (can be QString(), if it has been
132  * constructed with an empty home page)
133  */
134  QString webAddress() const;
135 
136  /**
137  * The person's Open Collaboration Services username
138  * @return the persons OCS username (can be QString(), if it has been
139  * constructed with an empty username)
140  */
141  QString ocsUsername() const;
142 
143  /**
144  * Creates a @c KAboutPerson from a JSON object with the following structure:
145  *
146  * Key | Accessor
147  * -----------| ----------------------------
148  * Name | name()
149  * Email | emailAddress()
150  * Task | task()
151  * Website | webAddress()
152  * UserName | ocsUsername()
153  *
154  * The @c Name and @c Task key are translatable (by using e.g. a "Task[de_DE]" key)
155  *
156  * @since 5.18
157  */
158  static KAboutPerson fromJSON(const QJsonObject &obj);
159 
160 private:
161  /**
162  * @internal Used by KAboutData to construct translator data.
163  */
164  explicit KAboutPerson(const QString &name, const QString &email, bool disambiguation);
165 
166 private:
168 };
169 
170 /**
171  * This class is used to store information about a license.
172  * The license can be one of some predefined, one given as text or one
173  * that can be loaded from a file. This class is used in the KAboutData class.
174  * Explicitly creating a KAboutLicense object is not possible.
175  * If the license is wanted for a KDE component having KAboutData object,
176  * use KAboutData::licenses() to get the licenses for that component.
177  * If the license is for a non-code resource and given by a keyword
178  * (e.g. in .desktop files), try using KAboutLicense::byKeyword().
179  */
180 class KCOREADDONS_EXPORT KAboutLicense
181 {
182  Q_GADGET
183  Q_PROPERTY(QString name READ name CONSTANT)
184  Q_PROPERTY(QString text READ text CONSTANT)
185  Q_PROPERTY(KAboutLicense::LicenseKey key READ key CONSTANT)
186  Q_PROPERTY(QString spdx READ spdx CONSTANT)
187  friend class KAboutData;
188  friend class KAboutComponent;
189 
190 public:
191  /**
192  * Describes the license of the software.
193  */
194  enum LicenseKey {
195  Custom = -2,
196  File = -1,
197  Unknown = 0,
198  GPL = 1,
199  GPL_V2 = 1,
200  LGPL = 2,
201  LGPL_V2 = 2,
202  BSDL = 3,
203  Artistic = 4,
204  QPL = 5,
205  QPL_V1_0 = 5,
206  GPL_V3 = 6,
207  LGPL_V3 = 7,
208  LGPL_V2_1 = 8, ///< @since 5.25
209  };
210  Q_ENUM(LicenseKey)
211 
212  /**
213  * Format of the license name.
214  */
215  enum NameFormat {
216  ShortName,
217  FullName,
218  };
219  Q_ENUM(NameFormat)
220 
221  /**
222  * Whether later versions of the license are allowed.
223  */
225  OnlyThisVersion,
226  OrLaterVersions,
227  };
228  Q_ENUM(VersionRestriction)
229 
230  /**
231  * @since 5.53
232  */
233  explicit KAboutLicense();
234 
235  /**
236  * Copy constructor. Performs a deep copy.
237  * @param other object to copy
238  */
239  KAboutLicense(const KAboutLicense &other);
240 
241  ~KAboutLicense();
242 
243  /**
244  * Assignment operator. Performs a deep copy.
245  * @param other object to copy
246  */
247  KAboutLicense &operator=(const KAboutLicense &other);
248 
249  /**
250  * Returns the full license text. If the licenseType argument of the
251  * constructor has been used, any text defined by setLicenseText is ignored,
252  * and the standard text for the chosen license will be returned.
253  *
254  * @return The license text.
255  */
256  QString text() const;
257 
258  /**
259  * Returns the license name.
260  *
261  * Default argument @since 5.53
262  *
263  * @return The license name as a string.
264  */
265  QString name(KAboutLicense::NameFormat formatName = ShortName) const;
266 
267  /**
268  * Returns the license key.
269  *
270  * @return The license key as element of KAboutLicense::LicenseKey enum.
271  */
272  KAboutLicense::LicenseKey key() const;
273 
274  /**
275  * Returns the SPDX license expression of this license.
276  * If the underlying license cannot be expressed as a SPDX expression a null string is returned.
277  *
278  * @note SPDX expression are expansive constructs. If you parse the return value, do it in a
279  * SPDX specification compliant manner by splitting on whitespaces to discard unwanted
280  * information or by using a complete SPDX license expression parser.
281  * @note SPDX identifiers are case-insensitive. Do not use case-sensitive checks on the return
282  * value.
283  * @see https://spdx.org/licenses
284  * @return SPDX license expression or QString() if the license has no identifier. Compliant
285  * with SPDX 2.1.
286  *
287  * @since 5.37
288  */
289  QString spdx() const;
290 
291  /**
292  * Fetch a known license by a keyword/spdx ID
293  *
294  * Frequently the license data is provided by a terse keyword-like string,
295  * e.g. by a field in a .desktop file. Using this method, an application
296  * can get hold of a proper KAboutLicense object, providing that the
297  * license is one of the several known to KDE, and use it to present
298  * more human-readable information to the user.
299  *
300  * Keywords are matched by stripping all whitespace and lowercasing.
301  * The known keywords correspond to the KAboutLicense::LicenseKey enumeration,
302  * e.g. any of "LGPLV3", "LGPLv3", "LGPL v3" would match KAboutLicense::LGPL_V3.
303  * If there is no match for the keyword, a valid license object is still
304  * returned, with its name and text informing about a custom license,
305  * and its key equal to KAboutLicense::Custom.
306  *
307  * @param keyword The license keyword.
308  * @return The license object.
309  *
310  * @see KAboutLicense::LicenseKey
311  */
312  static KAboutLicense byKeyword(const QString &keyword);
313 
314 private:
315  /**
316  * @internal Used by KAboutData to construct a predefined license.
317  */
318  explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType, enum KAboutLicense::VersionRestriction versionRestriction, const KAboutData *aboutData);
319  /**
320  * @internal Used by KAboutData to construct a predefined license.
321  */
322  explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType, const KAboutData *aboutData);
323  /**
324  * @internal Used by KAboutData to construct a KAboutLicense
325  */
326  explicit KAboutLicense(const KAboutData *aboutData);
327  /**
328  * @internal Used by KAboutData to construct license by given text
329  */
330  void setLicenseFromPath(const QString &pathToFile);
331  /**
332  * @internal Used by KAboutData to construct license by given text
333  */
334  void setLicenseFromText(const QString &licenseText);
335 
336 private:
338 };
339 
340 /**
341  * This class is used to store information about a third party component.
342  * It can store the component's name, a description, a link to a website
343  * and the license of the libary. This class is intended for use in the
344  * KAboutData class, but it can be used elsewhere as well.
345  * Normally you should at least define the libary's name.
346  * Creating a KAboutComponent object by yourself is relatively useless,
347  * but the KAboutData method KAboutData::libaries() return lists of
348  * KAboutComponent data objects which you can examine.
349  *
350  * Example usage within a main(), retrieving the list of components used
351  * by a program and re-using data from one of them:
352  *
353  * @code
354  * KAboutData about("khello", i18n("KHello"), "0.1",
355  * i18n("A KDE version of Hello, world!"),
356  * KAboutLicense::LGPL,
357  * i18n("Copyright (C) 2014 Developer"));
358  *
359  * about.addComponent(i18n("Awsom Lib"),
360  * i18n("Does awesom stuff. Copyright (C) 2014"),
361  * i18n("1.02.3"),
362  * "http://example.com",
363  * KAboutLicense::LGPL);
364  * QList<KAboutComponent> components = about.components();
365  * @endcode
366  *
367  * @since 5.84
368  */
369 class KCOREADDONS_EXPORT KAboutComponent
370 {
371  Q_GADGET
372  Q_PROPERTY(QString name READ name CONSTANT)
373  Q_PROPERTY(QString description READ description CONSTANT)
374  Q_PROPERTY(QString webAddress READ webAddress CONSTANT)
375  Q_PROPERTY(KAboutLicense licenses READ license CONSTANT)
376  Q_PROPERTY(QString version READ version CONSTANT)
377  friend class KAboutData;
378  friend class KAboutDataPrivate;
379 
380 public:
381  /**
382  * Convenience constructor
383  *
384  * @param name The name of the component.
385  *
386  * @param description The description of this component.
387  *
388  * @param version The version of this component.
389  *
390  * @param webAddress Website of the component.
391  *
392  * @param licenseType The license identifier of the component.
393  *
394  * @p name default argument
395  */
396  explicit KAboutComponent(const QString &name = QString(),
397  const QString &description = QString(),
398  const QString &version = QString(),
399  const QString &webAddress = QString(),
400  enum KAboutLicense::LicenseKey licenseType = KAboutLicense::Unknown);
401 
402  /**
403  * Convenience constructor
404  *
405  * @param name The name of the component.
406  *
407  * @param description The description of this component.
408  *
409  * @param version The version of this component.
410  *
411  * @param webAddress Website of the component.
412  *
413  * @param pathToLicenseFile Path to the file in the local filesystem containing the license text.
414  * The file format has to be plain text in an encoding compatible to the local.
415  *
416  * @p name default argument
417  */
418  explicit KAboutComponent(const QString &name,
419  const QString &description,
420  const QString &version,
421  const QString &webAddress,
422  const QString &pathToLicenseFile);
423 
424  /**
425  * Copy constructor. Performs a deep copy.
426  * @param other object to copy
427  */
428  KAboutComponent(const KAboutComponent &other);
429 
430  ~KAboutComponent();
431 
432  /**
433  * Assignment operator. Performs a deep copy.
434  * @param other object to copy
435  */
436  KAboutComponent &operator=(const KAboutComponent &other);
437 
438  /**
439  * The component's name
440  * @return the component's name (can be QString(), if it has been
441  * constructed with an empty name)
442  */
443  QString name() const;
444 
445  /**
446  * The component's description
447  * @return the component's description (can be empty)
448  */
449  QString description() const;
450 
451  /**
452  * The component's version
453  * @return the component's task (can be empty)
454  */
455  QString version() const;
456 
457  /**
458  * The website or a relevant link
459  * @return the component's website (can be empty)
460  */
461  QString webAddress() const;
462 
463  /**
464  * The component's license
465  * @return the component's KAboutLicense
466  */
467  KAboutLicense license() const;
468 
469 private:
471 };
472 
473 /**
474  * @class KAboutData kaboutdata.h KAboutData
475  *
476  * This class is used to store information about a program or plugin.
477  * It can store such values as version number, program name, home page, address
478  * for bug reporting, multiple authors and contributors
479  * (using KAboutPerson), license and copyright information.
480  *
481  * Currently, the values set here are shown by the "About" box
482  * (see KAboutDialog), used by the bug report dialog (see KBugReport),
483  * and by the help shown on command line (see KAboutData::setupCommandLine()).
484  *
485  * Porting Notes: Since KDE Frameworks 5.0, the translation catalog mechanism
486  * must be provided by your translation framework to load the correct catalog
487  * instead (eg: KLocalizedString::setApplicationDomain() for KI18n, or
488  * QCoreApplication::installTranslator() for Qt's translation system). This
489  * applies to the old setCatalogName() and catalogName() members. But see also
490  * K4AboutData in kde4support as a compatibility class.
491  *
492  * Example:
493  * Setting the metadata of an application using KAboutData in code also relying
494  * on the KDE Framework modules KI18n and KDBusAddons:
495  * @code
496  * // create QApplication instance
497  * QApplication app(argc, argv);
498  * // setup translation string domain for the i18n calls
499  * KLocalizedString::setApplicationDomain("foo");
500  * // create a KAboutData object to use for setting the application metadata
501  * KAboutData aboutData("foo", i18n("Foo"), "0.1",
502  * i18n("To Foo or not To Foo"),
503  * KAboutLicense::LGPL,
504  * i18n("Copyright 2017 Bar Foundation"), QString(),
505  * "https://www.foo-the-app.net");
506  * // overwrite default-generated values of organizationDomain & desktopFileName
507  * aboutData.setOrganizationDomain("barfoundation.org");
508  * aboutData.setDesktopFileName("org.barfoundation.foo");
509  *
510  * // set the application metadata
511  * KAboutData::setApplicationData(aboutData);
512  * // in GUI apps set the window icon manually, not covered by KAboutData
513  * // needed for environments where the icon name is not extracted from
514  * // the information in the application's desktop file
515  * QApplication::setWindowIcon(QIcon::fromTheme(QStringLiteral("foo")));
516  *
517  * // integrate with commandline argument handling
518  * QCommandLineParser parser;
519  * aboutData.setupCommandLine(&parser);
520  * // setup of app specific commandline args
521  * [...]
522  * parser.process(app);
523  * aboutData.processCommandLine(&parser);
524  *
525  * // with the application metadata set, register to the D-Bus session
526  * KDBusService programDBusService(KDBusService::Multiple | KDBusService::NoExitOnFailure);
527  * @endcode
528  *
529  * @short Holds information needed by the "About" box and other
530  * classes.
531  * @author Espen Sand ([email protected]), David Faure ([email protected])
532  *
533  */
534 class KCOREADDONS_EXPORT KAboutData
535 {
536  Q_GADGET
537  Q_PROPERTY(QString displayName READ displayName CONSTANT)
538  Q_PROPERTY(QString productName READ productName CONSTANT)
539  Q_PROPERTY(QString componentName READ componentName CONSTANT)
540  Q_PROPERTY(QVariant programLogo READ programLogo CONSTANT)
541  Q_PROPERTY(QString shortDescription READ shortDescription CONSTANT)
542  Q_PROPERTY(QString homepage READ homepage CONSTANT)
543  Q_PROPERTY(QString bugAddress READ bugAddress CONSTANT)
544  Q_PROPERTY(QString version READ version CONSTANT)
545  Q_PROPERTY(QString otherText READ otherText CONSTANT)
546  Q_PROPERTY(QVariantList authors READ authorsVariant CONSTANT) // constant in practice as addAuthor is not exposed to Q_GADGET
547  Q_PROPERTY(QVariantList credits READ creditsVariant CONSTANT)
548  Q_PROPERTY(QVariantList translators READ translatorsVariant CONSTANT)
549  Q_PROPERTY(QVariantList components READ componentsVariant CONSTANT)
550  Q_PROPERTY(QVariantList licenses READ licensesVariant CONSTANT)
551  Q_PROPERTY(QString copyrightStatement READ copyrightStatement CONSTANT)
552  Q_PROPERTY(QString desktopFileName READ desktopFileName CONSTANT)
553 public:
554  /**
555  * Returns the KAboutData for the application.
556  *
557  * This contains information such as authors, license, etc.,
558  * provided that setApplicationData has been called before.
559  * If not called before, the returned KAboutData will be initialized from the
560  * equivalent properties of QCoreApplication (and its subclasses),
561  * if an instance of that already exists.
562  * For the list of such properties see setApplicationData
563  * (before 5.22: limited to QCoreApplication::applicationName).
564  * @see setApplicationData
565  */
566  static KAboutData applicationData();
567 
568  /**
569  * Sets the application data for this application.
570  *
571  * In addition to changing the result of applicationData(), this initializes
572  * the equivalent properties of QCoreApplication (and its subclasses) with
573  * information from @p aboutData, if an instance of that already exists.
574  * Those properties are:
575  <ul>
576  <li>QCoreApplication::applicationName</li>
577  <li>QCoreApplication::applicationVersion</li>
578  <li>QCoreApplication::organizationDomain</li>
579  <li>QGuiApplication::applicationDisplayName</li>
580  <li>QGuiApplication::desktopFileName (since 5.16)</li>
581  </ul>
582  * @see applicationData
583  */
584  static void setApplicationData(const KAboutData &aboutData);
585 
586 // BUILD, not ENABLE, as producers need to support the registry for backward-compat
587 #if KCOREADDONS_BUILD_DEPRECATED_SINCE(5, 76)
588  /**
589  * Register the KAboutData information for a plugin.
590  * Call this from the constructor of the plugin.
591  * This will register the plugin's @p aboutData under the component name
592  * that was set in @p aboutData.
593  * @deprecated Since 5.76. The central registry is to be removed in the future
594  * in favour of plugin type specific local registries, using KPluginMetaData.
595  */
596  KCOREADDONS_DEPRECATED_VERSION(5, 76, "See API docs")
597  static void registerPluginData(const KAboutData &aboutData);
598 #endif
599 
600 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 76)
601  /**
602  * Return the KAboutData for the given plugin identified by @p componentName.
603  * @deprecated Since 5.76. The central registry is to be removed in the future
604  * in favour of plugin type specific local registries, using KPluginMetaData.
605  */
606  KCOREADDONS_DEPRECATED_VERSION(5, 76, "See API docs")
607  static KAboutData *pluginData(const QString &componentName);
608 #endif
609 
610 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 65)
611  /**
612  * Creates a @c KAboutData from the given @p plugin metadata
613  *
614  * @since 5.18
615  * @deprecated Since 5.65, use KAboutPluginDialog to show info about a plugin
616  * instead of KAboutApplicationDialog, with the latter having had been the
617  * only known need for this conversion.
618  */
619  KCOREADDONS_DEPRECATED_VERSION(5, 65, "See API docs")
620  static KAboutData fromPluginMetaData(const KPluginMetaData &plugin);
621 #endif
622 
623 public:
624  /**
625  * Constructor.
626  *
627  * Porting Note: The @p catalogName parameter present in KDE4 was
628  * deprecated and removed. See also K4AboutData
629  * in kde4support if this feature is needed for compatibility purposes, or
630  * consider using componentName() instead.
631  *
632  * @param componentName The program name or plugin name used internally.
633  * Example: QStringLiteral("kwrite"). This should never be translated.
634  *
635  * @param displayName A displayable name for the program or plugin. This string
636  * should be translated. Example: i18n("KWrite")
637  *
638  * @param version The component version string. Example: QStringLiteral("1.0").
639  *
640  * @param shortDescription A short description of what the component does.
641  * This string should be translated.
642  * Example: i18n("A simple text editor.")
643  *
644  * @param licenseType The license identifier. Use setLicenseText or
645  setLicenseTextFile if you use a license not predefined here.
646  *
647  * @param copyrightStatement A copyright statement, that can look like this:
648  * i18n("Copyright (C) 1999-2000 Name"). The string specified here is
649  * taken verbatim; the author information from addAuthor is not used.
650  *
651  * @param otherText Some free form text, that can contain any kind of
652  * information. The text can contain newlines. This string
653  * should be translated.
654  *
655  * @param homePageAddress The URL to the component's homepage, including
656  * URL scheme. "http://some.domain" is correct, "some.domain" is
657  * not. Since KDE Frameworks 5.17, https and other valid URL schemes
658  * are also valid. See also the note below.
659  *
660  * @param bugAddress The bug report address string, an email address or a URL.
661  * This defaults to the kde.org bug system.
662  *
663  * @note The @p homePageAddress argument is used to derive a default organization
664  * domain for the application (which is used to register on the session D-Bus,
665  * locate the appropriate desktop file, etc.), by taking the host name and dropping
666  * the first component, unless there are less than three (e.g. "www.kde.org" -> "kde.org").
667  * Use both setOrganizationDomain(const QByteArray&) and setDesktopFileName() if their default values
668  * do not have proper values.
669  *
670  * @see setOrganizationDomain(const QByteArray&), setDesktopFileName(const QString&)
671  */
672  // KF6: remove constructor that includes catalogName, and put default
673  // values back in for shortDescription and licenseType
674  KAboutData(const QString &componentName,
675  const QString &displayName,
676  const QString &version,
677  const QString &shortDescription,
678  enum KAboutLicense::LicenseKey licenseType,
679  const QString &copyrightStatement = QString(),
680  const QString &otherText = QString(),
681  const QString &homePageAddress = QString(),
682  const QString &bugAddress = QStringLiteral("[email protected]"));
683 
684  /**
685  * Constructor.
686  *
687  * @param componentName The program name or plugin name used internally.
688  * Example: "kwrite".
689  *
690  * @param displayName A displayable name for the program or plugin. This string
691  * should be translated. Example: i18n("KWrite")
692  *
693  * @param version The component version string.
694  *
695  * Sets the property desktopFileName to "org.kde."+componentName and
696  * the property organizationDomain to "kde.org".
697  *
698  * Default arguments @since 5.53
699  *
700  * @see setOrganizationDomain(const QByteArray&), setDesktopFileName(const QString&)
701  */
702  explicit KAboutData(const QString &componentName = {}, const QString &displayName = {}, const QString &version = {});
703 
704  /**
705  * Copy constructor. Performs a deep copy.
706  * @param other object to copy
707  */
708  KAboutData(const KAboutData &other);
709 
710  /**
711  * Assignment operator. Performs a deep copy.
712  * @param other object to copy
713  */
714  KAboutData &operator=(const KAboutData &other);
715 
716  ~KAboutData();
717 
718  /**
719  * Defines an author.
720  *
721  * You can call this function as many times as you need. Each entry is
722  * appended to a list. The person in the first entry is assumed to be
723  * the leader of the project.
724  *
725  * @param name The developer's name. It should be translated.
726  *
727  * @param task What the person is responsible for. This text can contain
728  * newlines. It should be translated.
729  * Can be left empty.
730  *
731  * @param emailAddress An Email address where the person can be reached.
732  * Can be left empty.
733  *
734  * @param webAddress The person's homepage or a relevant link.
735  * Start the address with "http://". "http://some.domain" is
736  * correct, "some.domain" is not. Can be left empty.
737  *
738  * @param ocsUsername The person's Open Collaboration Services username.
739  * The provider can be optionally specified with @see setOcsProvider.
740  *
741  */
742  KAboutData &addAuthor(const QString &name,
743  const QString &task = QString(),
744  const QString &emailAddress = QString(),
745  const QString &webAddress = QString(),
746  const QString &ocsUsername = QString());
747 
748  /**
749  * Defines a person that deserves credit.
750  *
751  * You can call this function as many times as you need. Each entry
752  * is appended to a list.
753  *
754  * @param name The person's name. It should be translated.
755  *
756  * @param task What the person has done to deserve the honor. The
757  * text can contain newlines. It should be translated.
758  * Can be left empty.
759  *
760  * @param emailAddress An email address when the person can be reached.
761  * Can be left empty.
762  *
763  * @param webAddress The person's homepage or a relevant link.
764  * Start the address with "http://". "http://some.domain" is
765  * is correct, "some.domain" is not. Can be left empty.
766  *
767  * @param ocsUsername The person's Open Collaboration Services username.
768  * The provider can be optionally specified with @see setOcsProvider.
769  *
770  */
771  KAboutData &addCredit(const QString &name,
772  const QString &task = QString(),
773  const QString &emailAddress = QString(),
774  const QString &webAddress = QString(),
775  const QString &ocsUsername = QString());
776 
777  /**
778  * @brief Sets the name(s) of the translator(s) of the GUI.
779  *
780  * The canonical use with the ki18n framework is:
781  *
782  * \code
783  * setTranslator(i18nc("NAME OF TRANSLATORS", "Your names"),
784  * i18nc("EMAIL OF TRANSLATORS", "Your emails"));
785  * \endcode
786  *
787  * If you are using a KMainWindow this is done for you automatically.
788  *
789  * The name and emailAddress are treated as lists separated with ",".
790  *
791  * If the strings are empty or "Your names"/"Your emails"
792  * respectively they will be ignored.
793  *
794  * @param name the name(s) of the translator(s)
795  * @param emailAddress the email address(es) of the translator(s)
796  * @see KAboutTranslator
797  */
798  KAboutData &setTranslator(const QString &name, const QString &emailAddress);
799 
800  /**
801  * Defines a component that is used by the application.
802  *
803  * You can call this function as many times as you need. Each entry is
804  * appended to a list.
805  *
806  * @param name The component's name. It should be translated.
807  *
808  * @param description Short description of the component and maybe
809  * copyright info. This text can contain newlines. It should
810  * be translated. Can be left empty.
811  *
812  * @param version The version of the component. Can be left empty.
813  *
814  * @param webAddress The component's homepage or a relevant link.
815  * Start the address with "http://". "http://some.domain" is
816  * correct, "some.domain" is not. Can be left empty.
817  *
818  * @param licenseKey The component's license identifier. Can be left empty (i.e. KAboutLicense::Unknown)
819  *
820  * @since 5.84
821  */
822  KAboutData &addComponent(const QString &name,
823  const QString &description = QString(),
824  const QString &version = QString(),
825  const QString &webAddress = QString(),
826  KAboutLicense::LicenseKey licenseKey = KAboutLicense::Unknown);
827 
828  /**
829  * Defines a component that is used by the application with a custom license text file.
830  *
831  * You can call this function as many times as you need. Each entry is
832  * appended to a list.
833  *
834  * @param name The component's name. It should be translated.
835  *
836  * @param description Short description of the component and maybe
837  * copyright info. This text can contain newlines. It should
838  * be translated. Can be left empty.
839  *
840  * @param version The version of the component. Can be left empty.
841  *
842  * @param webAddress The component's homepage or a relevant link.
843  * Start the address with "http://". "http://some.domain" is
844  * correct, "some.domain" is not. Can be left empty.
845  *
846  * @param pathToLicenseFile Path to the file in the local filesystem containing the license text.
847  * The file format has to be plain text in an encoding compatible to the local.
848  *
849  * @since 5.84
850  */
851  KAboutData &addComponent(const QString &name,
852  const QString &description,
853  const QString &version,
854  const QString &webAddress,
855  const QString &pathToLicenseFile);
856 
857  /**
858  * Defines a license text, which is translated.
859  *
860  * Example:
861  * \code
862  * setLicenseText( i18n("This is my license") );
863  * \endcode
864  *
865  * @param license The license text.
866  */
867  KAboutData &setLicenseText(const QString &license);
868 
869  /**
870  * Adds a license text, which is translated.
871  *
872  * If there is only one unknown license set, e.g. by using the default
873  * parameter in the constructor, that one is replaced.
874  *
875  * Example:
876  * \code
877  * addLicenseText( i18n("This is my license") );
878  * \endcode
879  *
880  * @param license The license text.
881  * @see setLicenseText, addLicense, addLicenseTextFile
882  */
883  KAboutData &addLicenseText(const QString &license);
884 
885  /**
886  * Defines a license text by pointing to a file where it resides.
887  * The file format has to be plain text in an encoding compatible to the locale.
888  *
889  * @param file Path to the file in the local filesystem containing the license text.
890  */
891  KAboutData &setLicenseTextFile(const QString &file);
892 
893  /**
894  * Adds a license text by pointing to a file where it resides.
895  * The file format has to be plain text in an encoding compatible to the locale.
896  *
897  * If there is only one unknown license set, e.g. by using the default
898  * parameter in the constructor, that one is replaced.
899  *
900  * @param file Path to the file in the local filesystem containing the license text.
901  * @see addLicenseText, addLicense, setLicenseTextFile
902  */
903  KAboutData &addLicenseTextFile(const QString &file);
904 
905  /**
906  * Defines the component name used internally.
907  *
908  * @param componentName The application or plugin name. Example: "kate".
909  */
910  KAboutData &setComponentName(const QString &componentName);
911 
912  /**
913  * Defines the displayable component name string.
914  *
915  * @param displayName The display name. This string should be
916  * translated.
917  * Example: i18n("Advanced Text Editor").
918  */
919  KAboutData &setDisplayName(const QString &displayName);
920 
921 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 2)
922  /**
923  * Obsolete method
924  *
925  * This method used to set the icon name but this is no longer
926  * possible in KDE Frameworks 5 because KCoreAddons does not
927  * depend on QtGui.
928  *
929  * @param iconName name of the icon. Example: "accessories-text-editor"
930  * @see programIconName()
931  *
932  * @deprecated since 5.2, use QApplication::setWindowIcon(QIcon::fromTheme()) instead.
933  */
934  KCOREADDONS_DEPRECATED_VERSION(5, 2, "Use QApplication::setWindowIcon")
935  KAboutData &setProgramIconName(const QString &iconName);
936 #endif
937  /**
938  * Defines the program logo.
939  *
940  * Use this if you need to have an application logo
941  * in AboutData other than the application icon.
942  *
943  * Because KAboutData is a core class it cannot use QImage/QPixmap/QIcon directly,
944  * so this is a QVariant that should contain a QImage/QPixmap/QIcon.
945  *
946  * QIcon should be preferred, to be able to properly handle HiDPI scaling.
947  * If a QIcon is provided, it will be used at a typical size of 48x48.
948  *
949  * @param image logo image.
950  * @see programLogo()
951  */
952  KAboutData &setProgramLogo(const QVariant &image);
953 
954  /**
955  * Specifies an Open Collaboration Services provider by URL.
956  * A provider file must be available for the chosen provider.
957  *
958  * Use this if you need to override the default provider.
959  *
960  * If this method is not used, all the KAboutPerson OCS usernames
961  * will be used with the openDesktop.org entry from the default
962  * provider file.
963  *
964  * @param providerUrl The provider URL as defined in the provider file.
965  */
966  KAboutData &setOcsProvider(const QString &providerUrl);
967 
968  /**
969  * Defines the program version string.
970  *
971  * @param version The program version.
972  */
973  KAboutData &setVersion(const QByteArray &version);
974 
975  /**
976  * Defines a short description of what the program does.
977  *
978  * @param shortDescription The program description. This string should
979  * be translated. Example: i18n("An advanced text
980  * editor with syntax highlighting support.").
981  */
982  KAboutData &setShortDescription(const QString &shortDescription);
983 
984  /**
985  * Defines the license identifier.
986  *
987  * @param licenseKey The license identifier.
988  * @see addLicenseText, setLicenseText, setLicenseTextFile
989  */
990  KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey);
991 
992  /**
993  * Defines the license identifier.
994  *
995  * @param licenseKey The license identifier.
996  * @param versionRestriction Whether later versions of the license are also allowed.
997  * e.g. licensed under "GPL 2.0 or at your option later versions" would be OrLaterVersions.
998  * @see addLicenseText, setLicenseText, setLicenseTextFile
999  *
1000  * @since 5.37
1001  */
1002  KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey, KAboutLicense::VersionRestriction versionRestriction);
1003 
1004  /**
1005  * Adds a license identifier.
1006  *
1007  * If there is only one unknown license set, e.g. by using the default
1008  * parameter in the constructor, that one is replaced.
1009  *
1010  * @param licenseKey The license identifier.
1011  * @see setLicenseText, addLicenseText, addLicenseTextFile
1012  */
1013  KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey);
1014 
1015  /**
1016  * Adds a license identifier.
1017  *
1018  * If there is only one unknown license set, e.g. by using the default
1019  * parameter in the constructor, that one is replaced.
1020  *
1021  * @param licenseKey The license identifier.
1022  * @param versionRestriction Whether later versions of the license are also allowed.
1023  * e.g. licensed under "GPL 2.0 or at your option later versions" would be OrLaterVersions.
1024  * @see setLicenseText, addLicenseText, addLicenseTextFile
1025  *
1026  * @since 5.37
1027  */
1028  KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey, KAboutLicense::VersionRestriction versionRestriction);
1029 
1030  /**
1031  * Defines the copyright statement to show when displaying the license.
1032  *
1033  * @param copyrightStatement A copyright statement, that can look like
1034  * this: i18n("Copyright (C) 1999-2000 Name"). The string specified here is
1035  * taken verbatim; the author information from addAuthor is not used.
1036  */
1037  KAboutData &setCopyrightStatement(const QString &copyrightStatement);
1038 
1039  /**
1040  * Defines the additional text to show in the about dialog.
1041  *
1042  * @param otherText Some free form text, that can contain any kind of
1043  * information. The text can contain newlines. This string
1044  * should be translated.
1045  */
1046  KAboutData &setOtherText(const QString &otherText);
1047 
1048  /**
1049  * Defines the program homepage.
1050  *
1051  * @param homepage The program homepage string.
1052  * Start the address with "http://". "http://kate.kde.org"
1053  * is correct but "kate.kde.org" is not.
1054  */
1055  KAboutData &setHomepage(const QString &homepage);
1056 
1057  /**
1058  * Defines the address where bug reports should be sent.
1059  *
1060  * @param bugAddress The bug report email address or URL.
1061  * This defaults to the kde.org bug system.
1062  */
1063  KAboutData &setBugAddress(const QByteArray &bugAddress);
1064 
1065  /**
1066  * Defines the domain of the organization that wrote this application.
1067  * The domain is set to kde.org by default, or the domain of the homePageAddress constructor argument,
1068  * if set.
1069  *
1070  * Make sure to call setOrganizationDomain(const QByteArray&) if your product
1071  * is not developed inside the KDE community.
1072  *
1073  * Used e.g. for the registration to D-Bus done by KDBusService
1074  * from the KDE Frameworks KDBusAddons module.
1075  *
1076  * Calling this method has no effect on the value of the desktopFileName property.
1077  *
1078  * @note If your program should work as a D-Bus activatable service, the base name
1079  * of the D-Bus service description file or of the desktop file you install must match
1080  * the D-Bus "well-known name" for which the program will register.
1081  * For example, KDBusService will use a name created from the reversed organization domain
1082  * with the component name attached, so for an organization domain "bar.org" and a
1083  * component name "foo" the name of an installed D-Bus service file needs to be
1084  * "org.bar.foo.service" or the name of the installed desktop file "org.bar.foo.desktop"
1085  * (and the desktopFileName property accordingly set to "org.bar.foo").
1086  * For still supporting the deprecated start of services via KToolInvocation,
1087  * the desktop file needs to have an entry with the key "X-DBUS-ServiceName"
1088  * and a value which matches the used D-Bus "well-known name" as just described,
1089  * so with the above used values it needs a line "X-DBUS-ServiceName=org.bar.foo"
1090  *
1091  * @param domain the domain name, for instance kde.org, koffice.org, etc.
1092  *
1093  * @see setDesktopFileName(const QString&)
1094  */
1095  KAboutData &setOrganizationDomain(const QByteArray &domain);
1096 
1097  /**
1098  * Defines the product name which will be used in the KBugReport dialog.
1099  * By default it's the componentName, but you can overwrite it here to provide
1100  * support for special components e.g. in the form 'product/component',
1101  * such as 'kontact/summary'.
1102  *
1103  * @param name The name of product
1104  */
1105  KAboutData &setProductName(const QByteArray &name);
1106 
1107  /**
1108  * Returns the application's internal name.
1109  * @return the internal program name.
1110  */
1111  QString componentName() const;
1112 
1113  /**
1114  * Returns the application's product name, which will be used in KBugReport
1115  * dialog. By default it returns componentName(), otherwise the one which is set
1116  * with setProductName()
1117  *
1118  * @return the product name.
1119  */
1120  QString productName() const;
1121 
1122  /**
1123  * @internal
1124  * Provided for use by KCrash
1125  */
1126  const char *internalProductName() const;
1127 
1128  /**
1129  * Returns the translated program name.
1130  * @return the program name (translated).
1131  */
1132  QString displayName() const;
1133 
1134  /**
1135  * Returns the domain name of the organization that wrote this application.
1136  *
1137  * @see setOrganizationDomain(const QByteArray&)
1138  */
1139  QString organizationDomain() const;
1140 
1141  /**
1142  * @internal
1143  * Provided for use by KCrash
1144  */
1145  const char *internalProgramName() const;
1146 
1147 // Not using KCOREADDONS_ENABLE_DEPRECATED_SINCE because KXmlGui and KConfigWidgets need this, for compat
1148 #if KCOREADDONS_BUILD_DEPRECATED_SINCE(5, 2)
1149  /**
1150  * Returns the program's icon name.
1151  *
1152  * The default value is componentName().
1153  * @return the program's icon name.
1154  *
1155  * This is mostly for compatibility, given that setProgramIconName is deprecated.
1156  * @deprecated Since 5.2, Use QGuiApplication::windowIcon instead
1157  */
1158  KCOREADDONS_DEPRECATED_VERSION(5, 2, "Use QGuiApplication::windowIcon instead")
1159  QString programIconName() const;
1160 #endif
1161 
1162  /**
1163  * Returns the program logo image.
1164  *
1165  * Because KAboutData is a core class it cannot use QImage/QPixmap/QIcon directly,
1166  * so this is a QVariant containing a QImage/QPixmap/QIcon.
1167  *
1168  * @return the program logo data, or a null image if there is
1169  * no custom application logo defined.
1170  */
1171  QVariant programLogo() const;
1172 
1173  /**
1174  * Returns the chosen Open Collaboration Services provider URL.
1175  * @return the provider URL.
1176  */
1177  QString ocsProviderUrl() const;
1178 
1179  /**
1180  * Returns the program's version.
1181  * @return the version string.
1182  */
1183  QString version() const;
1184 
1185  /**
1186  * @internal
1187  * Provided for use by KCrash
1188  */
1189  const char *internalVersion() const;
1190 
1191  /**
1192  * Returns a short, translated description.
1193  * @return the short description (translated). Can be
1194  * QString() if not set.
1195  */
1196  QString shortDescription() const;
1197 
1198  /**
1199  * Returns the application homepage.
1200  * @return the application homepage URL. Can be QString() if
1201  * not set.
1202  */
1203  QString homepage() const;
1204 
1205  /**
1206  * Returns the email address or URL for bugs.
1207  * @return the address where to report bugs.
1208  */
1209  QString bugAddress() const;
1210 
1211  /**
1212  * @internal
1213  * Provided for use by KCrash
1214  */
1215  const char *internalBugAddress() const;
1216 
1217  /**
1218  * Returns a list of authors.
1219  * @return author information (list of persons).
1220  */
1221  QList<KAboutPerson> authors() const;
1222 
1223  /**
1224  * Returns a list of persons who contributed.
1225  * @return credit information (list of persons).
1226  */
1227  QList<KAboutPerson> credits() const;
1228 
1229  /**
1230  * Returns a list of translators.
1231  * @return translators information (list of persons)
1232  */
1233  QList<KAboutPerson> translators() const;
1234 
1235  /**
1236  * Returns a message about the translation team.
1237  * @return a message about the translation team
1238  */
1239  static QString aboutTranslationTeam();
1240 
1241  /**
1242  * Returns a list of components.
1243  * @return component information (list of components).
1244  * @since 5.84
1245  */
1246  QList<KAboutComponent> components() const;
1247 
1248  /**
1249  * Returns a translated, free form text.
1250  * @return the free form text (translated). Can be QString() if not set.
1251  */
1252  QString otherText() const;
1253 
1254  /**
1255  * Returns a list of licenses.
1256  *
1257  * @return licenses information (list of licenses)
1258  */
1259  QList<KAboutLicense> licenses() const;
1260 
1261  /**
1262  * Returns the copyright statement.
1263  * @return the copyright statement. Can be QString() if not set.
1264  */
1265  QString copyrightStatement() const;
1266 
1267  /**
1268  * Returns the plain text displayed around the list of authors instead
1269  * of the default message telling users to send bug reports to bugAddress().
1270  *
1271  * @return the plain text displayed around the list of authors instead
1272  * of the default message. Can be QString().
1273  */
1274  QString customAuthorPlainText() const;
1275 
1276  /**
1277  * Returns the rich text displayed around the list of authors instead
1278  * of the default message telling users to send bug reports to bugAddress().
1279  *
1280  * @return the rich text displayed around the list of authors instead
1281  * of the default message. Can be QString().
1282  */
1283  QString customAuthorRichText() const;
1284 
1285  /**
1286  * Returns whether custom text should be displayed around the list of
1287  * authors.
1288  *
1289  * @return whether custom text should be displayed around the list of
1290  * authors.
1291  */
1292  bool customAuthorTextEnabled() const;
1293 
1294  /**
1295  * Sets the custom text displayed around the list of authors instead
1296  * of the default message telling users to send bug reports to bugAddress().
1297  *
1298  * @param plainText The plain text.
1299  * @param richText The rich text.
1300  *
1301  * Setting both to parameters to QString() will cause no message to be
1302  * displayed at all. Call unsetCustomAuthorText() to revert to the default
1303  * message.
1304  */
1305  KAboutData &setCustomAuthorText(const QString &plainText, const QString &richText);
1306 
1307  /**
1308  * Clears any custom text displayed around the list of authors and falls
1309  * back to the default message telling users to send bug reports to
1310  * bugAddress().
1311  */
1312  KAboutData &unsetCustomAuthorText();
1313 
1314  /**
1315  * Configures the @p parser command line parser to provide an authors entry with
1316  * information about the developers of the application and an entry specifying the license.
1317  *
1318  * Additionally, it will set the description to the command line parser, will add the help
1319  * option and if the QApplication has a version set (e.g. via KAboutData::setApplicationData)
1320  * it will also add the version option.
1321  *
1322  * Since 5.16 it also adds an option to set the desktop file name.
1323  *
1324  * @returns true if adding the options was successful; otherwise returns false.
1325  *
1326  * @sa processCommandLine()
1327  */
1328  bool setupCommandLine(QCommandLineParser *parser);
1329 
1330  /**
1331  * Reads the processed @p parser and sees if any of the arguments are the ones set
1332  * up from setupCommandLine().
1333  *
1334  * @sa setupCommandLine()
1335  */
1336  void processCommandLine(QCommandLineParser *parser);
1337 
1338  /**
1339  * Sets the base name of the desktop entry for this application.
1340  *
1341  * This is the file name, without the full path and without extension,
1342  * of the desktop entry that represents this application according to
1343  * the freedesktop desktop entry specification (e.g. "org.kde.foo").
1344  *
1345  * A default desktop file name is constructed when the KAboutData
1346  * object is created, using the reverse domain name of the
1347  * organizationDomain() and the componentName() as they are at the time
1348  * of the KAboutData object creation.
1349  * Call this method to override that default name. Typically this is
1350  * done when also setOrganizationDomain(const QByteArray&) or setComponentName(const QString&)
1351  * need to be called to override the initial values.
1352  *
1353  * The desktop file name can also be passed to the application at runtime through
1354  * the @c desktopfile command line option which is added by setupCommandLine(QCommandLineParser*).
1355  * This is useful if an application supports multiple desktop files with different runtime
1356  * settings.
1357  *
1358  * @param desktopFileName The desktop file name of this application
1359  *
1360  * @sa desktopFileName()
1361  * @sa organizationDomain()
1362  * @sa componentName()
1363  * @sa setupCommandLine(QCommandLineParser*)
1364  * @since 5.16
1365  **/
1366  KAboutData &setDesktopFileName(const QString &desktopFileName);
1367 
1368  /**
1369  * @returns The desktop file name of this application (e.g. "org.kde.foo")
1370  * @sa setDesktopFileName(const QString&)
1371  * @since 5.16
1372  **/
1373  QString desktopFileName() const;
1374 
1375 private:
1376  QVariantList licensesVariant() const;
1377  QVariantList authorsVariant() const;
1378  QVariantList creditsVariant() const;
1379  QVariantList translatorsVariant() const;
1380  QVariantList componentsVariant() const;
1381 
1382  friend void KCrash::defaultCrashHandler(int sig);
1383  static const KAboutData *applicationDataPointer();
1384 
1385 private:
1386  std::unique_ptr<class KAboutDataPrivate> const d;
1387 };
1388 
1389 Q_DECLARE_METATYPE(KAboutData)
1390 Q_DECLARE_METATYPE(KAboutLicense)
1391 Q_DECLARE_METATYPE(KAboutPerson)
1392 Q_DECLARE_METATYPE(KAboutComponent)
1393 
1394 #endif
This class is used to store information about a license.
Definition: kaboutdata.h:180
KAboutComponent & operator=(const KAboutComponent &other)
Assignment operator.
KCRASH_EXPORT void defaultCrashHandler(int signal)
This class is used to store information about a third party component.
Definition: kaboutdata.h:369
const QLatin1String name
This class is used to store information about a program or plugin.
Definition: kaboutdata.h:534
LicenseKey
Describes the license of the software.
Definition: kaboutdata.h:194
This class is used to store information about a person or developer.
Definition: kaboutdata.h:61
NameFormat
Format of the license name.
Definition: kaboutdata.h:215
This class allows easily accessing some standardized values from the JSON metadata that can be embedd...
VersionRestriction
Whether later versions of the license are allowed.
Definition: kaboutdata.h:224
QString name() const
The component&#39;s name.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Nov 26 2021 23:03:44 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.