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 <QUrl>
20 #include <QVariant>
21 #include <kcoreaddons_export.h>
22 #include <memory>
23 #include <qcontainerfwd.h>
24 
25 class QCommandLineParser;
26 class QJsonObject;
27 class KAboutData;
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(QUrl avatarUrl READ avatarUrl 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 avatarUrl URL to the avatar of the person, since 6.0
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 QUrl &avatarUrl = QUrl());
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  * @return an URL pointing to the user's avatar
138  * @since 6.0
139  */
140  QUrl avatarUrl() const;
141 
142  /**
143  * Creates a @c KAboutPerson from a JSON object with the following structure:
144  *
145  * Key | Accessor
146  * -----------| ----------------------------
147  * Name | name()
148  * Email | emailAddress()
149  * Task | task()
150  * Website | webAddress()
151  * AvatarUrl | avatarUrl()
152  *
153  * The @c Name and @c Task key are translatable (by using e.g. a "Task[de_DE]" key)
154  * The AvatarUrl exists since version 6.0
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  KCOREADDONS_NO_EXPORT 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; for more information see: https://spdx.org/licenses/
193  */
194  enum LicenseKey {
195  Custom = -2, ///< Custom license
196  File = -1, ///< License set from text file, see setLicenseFromPath()
197  Unknown = 0, ///< Unknown license
198  GPL = 1, ///< GPL
199  GPL_V2 = GPL, ///< GPL_V2, this has the same value as LicenseKey::GPL, see https://spdx.org/licenses/GPL-2.0.html
200  LGPL = 2, ///< LGPL
201  LGPL_V2 = LGPL, ///< LGPL_V2, this has the same value as LicenseKey::LGPL, see https://spdx.org/licenses/LGPL-2.0-only.html
202  BSDL = 3, ///< BSDL, see https://spdx.org/licenses/BSD-2-Clause.html
203  Artistic = 4, ///< Artistic, see https://spdx.org/licenses/Artistic-2.0.html
204  QPL = 5, ///< QPL
205  QPL_V1_0 = QPL, ///< QPL_V1_0, this has the same value as LicenseKey::QPL, see https://spdx.org/licenses/QPL-1.0.html
206  GPL_V3 = 6, ///< GPL_V3, see https://spdx.org/licenses/GPL-3.0.html
207  LGPL_V3 = 7, ///< LGPL_V3, see https://spdx.org/licenses/LGPL-3.0-only.html
208  LGPL_V2_1 = 8, ///< LGPL_V2_1 @since 5.25, see https://spdx.org/licenses/LGPL-2.1-only.html
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  KCOREADDONS_NO_EXPORT explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType,
319  enum KAboutLicense::VersionRestriction versionRestriction,
320  const KAboutData *aboutData);
321  /**
322  * @internal Used by KAboutData to construct a predefined license.
323  */
324  KCOREADDONS_NO_EXPORT explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType, const KAboutData *aboutData);
325  /**
326  * @internal Used by KAboutData to construct a KAboutLicense
327  */
328  KCOREADDONS_NO_EXPORT explicit KAboutLicense(const KAboutData *aboutData);
329  /**
330  * @internal Used by KAboutData to construct license by given text
331  */
332  KCOREADDONS_NO_EXPORT void setLicenseFromPath(const QString &pathToFile);
333  /**
334  * @internal Used by KAboutData to construct license by given text
335  */
336  KCOREADDONS_NO_EXPORT void setLicenseFromText(const QString &licenseText);
337 
338 private:
340 };
341 
342 /**
343  * This class is used to store information about a third party component.
344  * It can store the component's name, a description, a link to a website
345  * and the license of the libary. This class is intended for use in the
346  * KAboutData class, but it can be used elsewhere as well.
347  * Normally you should at least define the libary's name.
348  * Creating a KAboutComponent object by yourself is relatively useless,
349  * but the KAboutData method KAboutData::libaries() return lists of
350  * KAboutComponent data objects which you can examine.
351  *
352  * Example usage within a main(), retrieving the list of components used
353  * by a program and re-using data from one of them:
354  *
355  * @code
356  * KAboutData about("khello", i18n("KHello"), "0.1",
357  * i18n("A KDE version of Hello, world!"),
358  * KAboutLicense::LGPL,
359  * i18n("Copyright (C) 2014 Developer"));
360  *
361  * about.addComponent(i18n("Awsom Lib"),
362  * i18n("Does awesom stuff. Copyright (C) 2014"),
363  * i18n("1.02.3"),
364  * "http://example.com",
365  * KAboutLicense::LGPL);
366  * QList<KAboutComponent> components = about.components();
367  * @endcode
368  *
369  * @since 5.84
370  */
371 class KCOREADDONS_EXPORT KAboutComponent
372 {
373  Q_GADGET
374  Q_PROPERTY(QString name READ name CONSTANT)
375  Q_PROPERTY(QString description READ description CONSTANT)
376  Q_PROPERTY(QString webAddress READ webAddress CONSTANT)
377  Q_PROPERTY(KAboutLicense licenses READ license CONSTANT)
378  Q_PROPERTY(QString version READ version CONSTANT)
379  friend class KAboutData;
380  friend class KAboutDataPrivate;
381 
382 public:
383  /**
384  * Convenience constructor
385  *
386  * @param name The name of the component.
387  *
388  * @param description The description of this component.
389  *
390  * @param version The version of this component.
391  *
392  * @param webAddress Website of the component.
393  *
394  * @param licenseType The license identifier of the component.
395  *
396  * @p name default argument
397  */
398  explicit KAboutComponent(const QString &name = QString(),
399  const QString &description = QString(),
400  const QString &version = QString(),
401  const QString &webAddress = QString(),
403 
404  /**
405  * Convenience constructor
406  *
407  * @param name The name of the component.
408  *
409  * @param description The description of this component.
410  *
411  * @param version The version of this component.
412  *
413  * @param webAddress Website of the component.
414  *
415  * @param pathToLicenseFile Path to the file in the local filesystem containing the license text.
416  * The file format has to be plain text in an encoding compatible to the local.
417  *
418  * @p name default argument
419  */
420  explicit KAboutComponent(const QString &name,
421  const QString &description,
422  const QString &version,
423  const QString &webAddress,
424  const QString &pathToLicenseFile);
425 
426  /**
427  * Copy constructor. Performs a deep copy.
428  * @param other object to copy
429  */
430  KAboutComponent(const KAboutComponent &other);
431 
432  ~KAboutComponent();
433 
434  /**
435  * Assignment operator. Performs a deep copy.
436  * @param other object to copy
437  */
438  KAboutComponent &operator=(const KAboutComponent &other);
439 
440  /**
441  * The component's name
442  * @return the component's name (can be QString(), if it has been
443  * constructed with an empty name)
444  */
445  QString name() const;
446 
447  /**
448  * The component's description
449  * @return the component's description (can be empty)
450  */
451  QString description() const;
452 
453  /**
454  * The component's version
455  * @return the component's task (can be empty)
456  */
457  QString version() const;
458 
459  /**
460  * The website or a relevant link
461  * @return the component's website (can be empty)
462  */
463  QString webAddress() const;
464 
465  /**
466  * The component's license
467  * @return the component's KAboutLicense
468  */
469  KAboutLicense license() const;
470 
471 private:
473 };
474 
475 /**
476  * @class KAboutData kaboutdata.h KAboutData
477  *
478  * This class is used to store information about a program or plugin.
479  * It can store such values as version number, program name, home page, address
480  * for bug reporting, multiple authors and contributors
481  * (using KAboutPerson), license and copyright information.
482  *
483  * Currently, the values set here are shown by the "About" box
484  * (see KAboutDialog), used by the bug report dialog (see KBugReport),
485  * and by the help shown on command line (see KAboutData::setupCommandLine()).
486  *
487  * Porting Notes: Since KDE Frameworks 5.0, the translation catalog mechanism
488  * must be provided by your translation framework to load the correct catalog
489  * instead (eg: KLocalizedString::setApplicationDomain() for KI18n, or
490  * QCoreApplication::installTranslator() for Qt's translation system). This
491  * applies to the old setCatalogName() and catalogName() members. But see also
492  * K4AboutData in kde4support as a compatibility class.
493  *
494  * Example:
495  * Setting the metadata of an application using KAboutData in code also relying
496  * on the KDE Framework modules KI18n and KDBusAddons:
497  * @code
498  * // create QApplication instance
499  * QApplication app(argc, argv);
500  * // setup translation string domain for the i18n calls
501  * KLocalizedString::setApplicationDomain("foo");
502  * // create a KAboutData object to use for setting the application metadata
503  * KAboutData aboutData("foo", i18n("Foo"), "0.1",
504  * i18n("To Foo or not To Foo"),
505  * KAboutLicense::LGPL,
506  * i18n("Copyright 2017 Bar Foundation"), QString(),
507  * "https://www.foo-the-app.net");
508  * // overwrite default-generated values of organizationDomain & desktopFileName
509  * aboutData.setOrganizationDomain("barfoundation.org");
510  * aboutData.setDesktopFileName("org.barfoundation.foo");
511  *
512  * // set the application metadata
513  * KAboutData::setApplicationData(aboutData);
514  * // in GUI apps set the window icon manually, not covered by KAboutData
515  * // needed for environments where the icon name is not extracted from
516  * // the information in the application's desktop file
517  * QApplication::setWindowIcon(QIcon::fromTheme(QStringLiteral("foo")));
518  *
519  * // integrate with commandline argument handling
520  * QCommandLineParser parser;
521  * aboutData.setupCommandLine(&parser);
522  * // setup of app specific commandline args
523  * [...]
524  * parser.process(app);
525  * aboutData.processCommandLine(&parser);
526  *
527  * // with the application metadata set, register to the D-Bus session
528  * KDBusService programDBusService(KDBusService::Multiple | KDBusService::NoExitOnFailure);
529  * @endcode
530  *
531  * @short Holds information needed by the "About" box and other
532  * classes.
533  * @author Espen Sand ([email protected]), David Faure ([email protected])
534  *
535  */
536 class KCOREADDONS_EXPORT KAboutData
537 {
538  Q_GADGET
539  Q_PROPERTY(QString displayName READ displayName CONSTANT)
540  Q_PROPERTY(QString productName READ productName CONSTANT)
541  Q_PROPERTY(QString componentName READ componentName CONSTANT)
542  Q_PROPERTY(QVariant programLogo READ programLogo CONSTANT)
543  Q_PROPERTY(QString shortDescription READ shortDescription CONSTANT)
544  Q_PROPERTY(QString homepage READ homepage CONSTANT)
545  Q_PROPERTY(QString bugAddress READ bugAddress CONSTANT)
546  Q_PROPERTY(QString version READ version CONSTANT)
547  Q_PROPERTY(QString otherText READ otherText CONSTANT)
548  Q_PROPERTY(QList<KAboutPerson> authors READ authors CONSTANT) // constant in practice as addAuthor is not exposed to Q_GADGET
549  Q_PROPERTY(QList<KAboutPerson> credits READ credits CONSTANT)
550  Q_PROPERTY(QList<KAboutPerson> translators READ translators CONSTANT)
551  Q_PROPERTY(QList<KAboutComponent> components READ components CONSTANT)
552  Q_PROPERTY(QList<KAboutLicense> licenses READ licenses CONSTANT)
553  Q_PROPERTY(QString copyrightStatement READ copyrightStatement CONSTANT)
554  Q_PROPERTY(QString desktopFileName READ desktopFileName CONSTANT)
555 public:
556  /**
557  * Returns the KAboutData for the application.
558  *
559  * This contains information such as authors, license, etc.,
560  * provided that setApplicationData has been called before.
561  * If not called before, the returned KAboutData will be initialized from the
562  * equivalent properties of QCoreApplication (and its subclasses),
563  * if an instance of that already exists.
564  * For the list of such properties see setApplicationData
565  * (before 5.22: limited to QCoreApplication::applicationName).
566  * @see setApplicationData
567  */
568  static KAboutData applicationData();
569 
570  /**
571  * Sets the application data for this application.
572  *
573  * In addition to changing the result of applicationData(), this initializes
574  * the equivalent properties of QCoreApplication (and its subclasses) with
575  * information from @p aboutData, if an instance of that already exists.
576  * Those properties are:
577  <ul>
578  <li>QCoreApplication::applicationName</li>
579  <li>QCoreApplication::applicationVersion</li>
580  <li>QCoreApplication::organizationDomain</li>
581  <li>QGuiApplication::applicationDisplayName</li>
582  <li>QGuiApplication::desktopFileName (since 5.16)</li>
583  </ul>
584  * @see applicationData
585  */
586  static void setApplicationData(const KAboutData &aboutData);
587 
588 public:
589  /**
590  * Constructor.
591  *
592  * Porting Note: The @p catalogName parameter present in KDE4 was
593  * deprecated and removed. See also K4AboutData
594  * in kde4support if this feature is needed for compatibility purposes, or
595  * consider using componentName() instead.
596  *
597  * @param componentName The program name or plugin name used internally.
598  * Example: QStringLiteral("kwrite"). This should never be translated.
599  *
600  * @param displayName A displayable name for the program or plugin. This string
601  * should be translated. Example: i18n("KWrite")
602  *
603  * @param version The component version string. Example: QStringLiteral("1.0").
604  *
605  * @param shortDescription A short description of what the component does.
606  * This string should be translated.
607  * Example: i18n("A simple text editor.")
608  *
609  * @param licenseType The license identifier. Use setLicenseText or
610  setLicenseTextFile if you use a license not predefined here.
611  *
612  * @param copyrightStatement A copyright statement, that can look like this:
613  * i18n("Copyright (C) 1999-2000 Name"). The string specified here is
614  * taken verbatim; the author information from addAuthor is not used.
615  *
616  * @param otherText Some free form text, that can contain any kind of
617  * information. The text can contain newlines. This string
618  * should be translated.
619  *
620  * @param homePageAddress The URL to the component's homepage, including
621  * URL scheme. "http://some.domain" is correct, "some.domain" is
622  * not. Since KDE Frameworks 5.17, https and other valid URL schemes
623  * are also valid. See also the note below.
624  *
625  * @param bugAddress The bug report address string, an email address or a URL.
626  * This defaults to the kde.org bug system.
627  *
628  * @note The @p homePageAddress argument is used to derive a default organization
629  * domain for the application (which is used to register on the session D-Bus,
630  * locate the appropriate desktop file, etc.), by taking the host name and dropping
631  * the first component, unless there are less than three (e.g. "www.kde.org" -> "kde.org").
632  * Use both setOrganizationDomain(const QByteArray&) and setDesktopFileName() if their default values
633  * do not have proper values.
634  *
635  * @see setOrganizationDomain(const QByteArray&), setDesktopFileName(const QString&)
636  */
637  // KF6: remove constructor that includes catalogName, and put default
638  // values back in for shortDescription and licenseType
639  KAboutData(const QString &componentName,
640  const QString &displayName,
641  const QString &version,
642  const QString &shortDescription,
643  enum KAboutLicense::LicenseKey licenseType,
644  const QString &copyrightStatement = QString(),
645  const QString &otherText = QString(),
646  const QString &homePageAddress = QString(),
647  const QString &bugAddress = QStringLiteral("[email protected]"));
648 
649  /**
650  * Constructor.
651  *
652  * @param componentName The program name or plugin name used internally.
653  * Example: "kwrite".
654  *
655  * @param displayName A displayable name for the program or plugin. This string
656  * should be translated. Example: i18n("KWrite")
657  *
658  * @param version The component version string.
659  *
660  * Sets the property desktopFileName to "org.kde."+componentName and
661  * the property organizationDomain to "kde.org".
662  *
663  * Default arguments @since 5.53
664  *
665  * @see setOrganizationDomain(const QByteArray&), setDesktopFileName(const QString&)
666  */
667  explicit KAboutData(const QString &componentName = {}, const QString &displayName = {}, const QString &version = {});
668 
669  /**
670  * Copy constructor. Performs a deep copy.
671  * @param other object to copy
672  */
673  KAboutData(const KAboutData &other);
674 
675  /**
676  * Assignment operator. Performs a deep copy.
677  * @param other object to copy
678  */
679  KAboutData &operator=(const KAboutData &other);
680 
681  ~KAboutData();
682 
683  /**
684  * Defines an author.
685  *
686  * You can call this function as many times as you need. Each entry is
687  * appended to a list. The person in the first entry is assumed to be
688  * the leader of the project.
689  *
690  * @param name The developer's name. It should be translated.
691  *
692  * @param task What the person is responsible for. This text can contain
693  * newlines. It should be translated.
694  * Can be left empty.
695  *
696  * @param emailAddress An Email address where the person can be reached.
697  * Can be left empty.
698  *
699  * @param webAddress The person's homepage or a relevant link.
700  * Start the address with "http://". "http://some.domain" is
701  * correct, "some.domain" is not. Can be left empty.
702  *
703  * @param avatarUrl URL to the avatar of the person
704  */
705  KAboutData &addAuthor(const QString &name,
706  const QString &task = QString(),
707  const QString &emailAddress = QString(),
708  const QString &webAddress = QString(),
709  const QUrl &avatarUrl = QUrl());
710 
711  /**
712  * @overload
713  * @since 6.0
714  */
715  KAboutData &addAuthor(const QString &name, const QString &task, const QString &emailAddress, const QString &webAddress, const QString &kdeStoreUsername)
716  {
717  return addAuthor(name, task, emailAddress, webAddress, QUrl(QStringLiteral("https://store.kde.org/avatar/") + kdeStoreUsername));
718  }
719 
720  /**
721  * Defines a person that deserves credit.
722  *
723  * You can call this function as many times as you need. Each entry
724  * is appended to a list.
725  *
726  * @param name The person's name. It should be translated.
727  *
728  * @param task What the person has done to deserve the honor. The
729  * text can contain newlines. It should be translated.
730  * Can be left empty.
731  *
732  * @param emailAddress An email address when the person can be reached.
733  * Can be left empty.
734  *
735  * @param webAddress The person's homepage or a relevant link.
736  * Start the address with "http://". "http://some.domain" is
737  * is correct, "some.domain" is not. Can be left empty.
738  *
739  * @param avatarUrl URL to the avatar of the person
740  */
741  KAboutData &addCredit(const QString &name,
742  const QString &task = QString(),
743  const QString &emailAddress = QString(),
744  const QString &webAddress = QString(),
745  const QUrl &avatarUrl = QUrl());
746 
747  /**
748  * @overload
749  * @since 6.0
750  */
751  KAboutData &addCredit(const QString &name, const QString &task, const QString &emailAddress, const QString &webAddress, const QString &kdeStoreUsername)
752  {
753  return addCredit(name, task, emailAddress, webAddress, QUrl(QStringLiteral("https://store.kde.org/avatar/") + kdeStoreUsername));
754  }
755 
756  /**
757  * @brief Sets the name(s) of the translator(s) of the GUI.
758  *
759  * The canonical use with the ki18n framework is:
760  *
761  * \code
762  * setTranslator(i18nc("NAME OF TRANSLATORS", "Your names"),
763  * i18nc("EMAIL OF TRANSLATORS", "Your emails"));
764  * \endcode
765  *
766  * If you are using a KMainWindow this is done for you automatically.
767  *
768  * The name and emailAddress are treated as lists separated with ",".
769  *
770  * If the strings are empty or "Your names"/"Your emails"
771  * respectively they will be ignored.
772  *
773  * @param name the name(s) of the translator(s)
774  * @param emailAddress the email address(es) of the translator(s)
775  * @see KAboutTranslator
776  */
777  KAboutData &setTranslator(const QString &name, const QString &emailAddress);
778 
779  /**
780  * Defines a component that is used by the application.
781  *
782  * You can call this function as many times as you need. Each entry is
783  * appended to a list.
784  *
785  * @param name The component's name. It should be translated.
786  *
787  * @param description Short description of the component and maybe
788  * copyright info. This text can contain newlines. It should
789  * be translated. Can be left empty.
790  *
791  * @param version The version of the component. Can be left empty.
792  *
793  * @param webAddress The component's homepage or a relevant link.
794  * Start the address with "http://". "http://some.domain" is
795  * correct, "some.domain" is not. Can be left empty.
796  *
797  * @param licenseKey The component's license identifier. Can be left empty (i.e. KAboutLicense::Unknown)
798  *
799  * @since 5.84
800  */
801  KAboutData &addComponent(const QString &name,
802  const QString &description = QString(),
803  const QString &version = QString(),
804  const QString &webAddress = QString(),
806 
807  /**
808  * Defines a component that is used by the application with a custom license text file.
809  *
810  * You can call this function as many times as you need. Each entry is
811  * appended to a list.
812  *
813  * @param name The component's name. It should be translated.
814  *
815  * @param description Short description of the component and maybe
816  * copyright info. This text can contain newlines. It should
817  * be translated. Can be left empty.
818  *
819  * @param version The version of the component. Can be left empty.
820  *
821  * @param webAddress The component's homepage or a relevant link.
822  * Start the address with "http://". "http://some.domain" is
823  * correct, "some.domain" is not. Can be left empty.
824  *
825  * @param pathToLicenseFile Path to the file in the local filesystem containing the license text.
826  * The file format has to be plain text in an encoding compatible to the local.
827  *
828  * @since 5.84
829  */
830  KAboutData &
831  addComponent(const QString &name, const QString &description, const QString &version, const QString &webAddress, const QString &pathToLicenseFile);
832 
833  /**
834  * Defines a license text, which is translated.
835  *
836  * Example:
837  * \code
838  * setLicenseText( i18n("This is my license") );
839  * \endcode
840  *
841  * @param license The license text.
842  */
843  KAboutData &setLicenseText(const QString &license);
844 
845  /**
846  * Adds a license text, which is translated.
847  *
848  * If there is only one unknown license set, e.g. by using the default
849  * parameter in the constructor, that one is replaced.
850  *
851  * Example:
852  * \code
853  * addLicenseText( i18n("This is my license") );
854  * \endcode
855  *
856  * @param license The license text.
857  * @see setLicenseText, addLicense, addLicenseTextFile
858  */
859  KAboutData &addLicenseText(const QString &license);
860 
861  /**
862  * Defines a license text by pointing to a file where it resides.
863  * The file format has to be plain text in an encoding compatible to the locale.
864  *
865  * @param file Path to the file in the local filesystem containing the license text.
866  */
867  KAboutData &setLicenseTextFile(const QString &file);
868 
869  /**
870  * Adds a license text by pointing to a file where it resides.
871  * The file format has to be plain text in an encoding compatible to the locale.
872  *
873  * If there is only one unknown license set, e.g. by using the default
874  * parameter in the constructor, that one is replaced.
875  *
876  * @param file Path to the file in the local filesystem containing the license text.
877  * @see addLicenseText, addLicense, setLicenseTextFile
878  */
879  KAboutData &addLicenseTextFile(const QString &file);
880 
881  /**
882  * Defines the component name used internally.
883  *
884  * @param componentName The application or plugin name. Example: "kate".
885  */
886  KAboutData &setComponentName(const QString &componentName);
887 
888  /**
889  * Defines the displayable component name string.
890  *
891  * @param displayName The display name. This string should be
892  * translated.
893  * Example: i18n("Advanced Text Editor").
894  */
895  KAboutData &setDisplayName(const QString &displayName);
896 
897  /**
898  * Defines the program logo.
899  *
900  * Use this if you need to have an application logo
901  * in AboutData other than the application icon.
902  *
903  * Because KAboutData is a core class it cannot use QImage/QPixmap/QIcon directly,
904  * so this is a QVariant that should contain a QImage/QPixmap/QIcon.
905  *
906  * QIcon should be preferred, to be able to properly handle HiDPI scaling.
907  * If a QIcon is provided, it will be used at a typical size of 48x48.
908  *
909  * @param image logo image.
910  * @see programLogo()
911  */
912  KAboutData &setProgramLogo(const QVariant &image);
913 
914  /**
915  * Defines the program version string.
916  *
917  * @param version The program version.
918  */
919  KAboutData &setVersion(const QByteArray &version);
920 
921  /**
922  * Defines a short description of what the program does.
923  *
924  * @param shortDescription The program description. This string should
925  * be translated. Example: i18n("An advanced text
926  * editor with syntax highlighting support.").
927  */
928  KAboutData &setShortDescription(const QString &shortDescription);
929 
930  /**
931  * Defines the license identifier.
932  *
933  * @param licenseKey The license identifier.
934  * @see addLicenseText, setLicenseText, setLicenseTextFile
935  */
936  KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey);
937 
938  /**
939  * Defines the license identifier.
940  *
941  * @param licenseKey The license identifier.
942  * @param versionRestriction Whether later versions of the license are also allowed.
943  * e.g. licensed under "GPL 2.0 or at your option later versions" would be OrLaterVersions.
944  * @see addLicenseText, setLicenseText, setLicenseTextFile
945  *
946  * @since 5.37
947  */
948  KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey, KAboutLicense::VersionRestriction versionRestriction);
949 
950  /**
951  * Adds a license identifier.
952  *
953  * If there is only one unknown license set, e.g. by using the default
954  * parameter in the constructor, that one is replaced.
955  *
956  * @param licenseKey The license identifier.
957  * @see setLicenseText, addLicenseText, addLicenseTextFile
958  */
959  KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey);
960 
961  /**
962  * Adds a license identifier.
963  *
964  * If there is only one unknown license set, e.g. by using the default
965  * parameter in the constructor, that one is replaced.
966  *
967  * @param licenseKey The license identifier.
968  * @param versionRestriction Whether later versions of the license are also allowed.
969  * e.g. licensed under "GPL 2.0 or at your option later versions" would be OrLaterVersions.
970  * @see setLicenseText, addLicenseText, addLicenseTextFile
971  *
972  * @since 5.37
973  */
974  KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey, KAboutLicense::VersionRestriction versionRestriction);
975 
976  /**
977  * Defines the copyright statement to show when displaying the license.
978  *
979  * @param copyrightStatement A copyright statement, that can look like
980  * this: i18n("Copyright (C) 1999-2000 Name"). The string specified here is
981  * taken verbatim; the author information from addAuthor is not used.
982  */
983  KAboutData &setCopyrightStatement(const QString &copyrightStatement);
984 
985  /**
986  * Defines the additional text to show in the about dialog.
987  *
988  * @param otherText Some free form text, that can contain any kind of
989  * information. The text can contain newlines. This string
990  * should be translated.
991  */
992  KAboutData &setOtherText(const QString &otherText);
993 
994  /**
995  * Defines the program homepage.
996  *
997  * @param homepage The program homepage string.
998  * Start the address with "http://". "http://kate.kde.org"
999  * is correct but "kate.kde.org" is not.
1000  */
1001  KAboutData &setHomepage(const QString &homepage);
1002 
1003  /**
1004  * Defines the address where bug reports should be sent.
1005  *
1006  * @param bugAddress The bug report email address or URL.
1007  * This defaults to the kde.org bug system.
1008  */
1009  KAboutData &setBugAddress(const QByteArray &bugAddress);
1010 
1011  /**
1012  * Defines the domain of the organization that wrote this application.
1013  * The domain is set to kde.org by default, or the domain of the homePageAddress constructor argument,
1014  * if set.
1015  *
1016  * Make sure to call setOrganizationDomain(const QByteArray&) if your product
1017  * is not developed inside the KDE community.
1018  *
1019  * Used e.g. for the registration to D-Bus done by KDBusService
1020  * from the KDE Frameworks KDBusAddons module.
1021  *
1022  * Calling this method has no effect on the value of the desktopFileName property.
1023  *
1024  * @note If your program should work as a D-Bus activatable service, the base name
1025  * of the D-Bus service description file or of the desktop file you install must match
1026  * the D-Bus "well-known name" for which the program will register.
1027  * For example, KDBusService will use a name created from the reversed organization domain
1028  * with the component name attached, so for an organization domain "bar.org" and a
1029  * component name "foo" the name of an installed D-Bus service file needs to be
1030  * "org.bar.foo.service" or the name of the installed desktop file "org.bar.foo.desktop"
1031  * (and the desktopFileName property accordingly set to "org.bar.foo").
1032  *
1033  * @param domain the domain name, for instance kde.org, koffice.org, etc.
1034  *
1035  * @see setDesktopFileName(const QString&)
1036  */
1037  KAboutData &setOrganizationDomain(const QByteArray &domain);
1038 
1039  /**
1040  * Defines the product name which will be used in the KBugReport dialog.
1041  * By default it's the componentName, but you can overwrite it here to provide
1042  * support for special components e.g. in the form 'product/component',
1043  * such as 'kontact/summary'.
1044  *
1045  * @param name The name of product
1046  */
1047  KAboutData &setProductName(const QByteArray &name);
1048 
1049  /**
1050  * Returns the application's internal name.
1051  * @return the internal program name.
1052  */
1053  QString componentName() const;
1054 
1055  /**
1056  * Returns the application's product name, which will be used in KBugReport
1057  * dialog. By default it returns componentName(), otherwise the one which is set
1058  * with setProductName()
1059  *
1060  * @return the product name.
1061  */
1062  QString productName() const;
1063 
1064  /**
1065  * @internal
1066  * Provided for use by KCrash
1067  */
1068  const char *internalProductName() const;
1069 
1070  /**
1071  * Returns the translated program name.
1072  * @return the program name (translated).
1073  */
1074  QString displayName() const;
1075 
1076  /**
1077  * Returns the domain name of the organization that wrote this application.
1078  *
1079  * @see setOrganizationDomain(const QByteArray&)
1080  */
1081  QString organizationDomain() const;
1082 
1083  /**
1084  * @internal
1085  * Provided for use by KCrash
1086  */
1087  const char *internalProgramName() const;
1088 
1089  /**
1090  * Returns the program logo image.
1091  *
1092  * Because KAboutData is a core class it cannot use QImage/QPixmap/QIcon directly,
1093  * so this is a QVariant containing a QImage/QPixmap/QIcon.
1094  *
1095  * @return the program logo data, or a null image if there is
1096  * no custom application logo defined.
1097  */
1098  QVariant programLogo() const;
1099 
1100  /**
1101  * Returns the program's version.
1102  * @return the version string.
1103  */
1104  QString version() const;
1105 
1106  /**
1107  * @internal
1108  * Provided for use by KCrash
1109  */
1110  const char *internalVersion() const;
1111 
1112  /**
1113  * Returns a short, translated description.
1114  * @return the short description (translated). Can be
1115  * QString() if not set.
1116  */
1117  QString shortDescription() const;
1118 
1119  /**
1120  * Returns the application homepage.
1121  * @return the application homepage URL. Can be QString() if
1122  * not set.
1123  */
1124  QString homepage() const;
1125 
1126  /**
1127  * Returns the email address or URL for bugs.
1128  * @return the address where to report bugs.
1129  */
1130  QString bugAddress() const;
1131 
1132  /**
1133  * @internal
1134  * Provided for use by KCrash
1135  */
1136  const char *internalBugAddress() const;
1137 
1138  /**
1139  * Returns a list of authors.
1140  * @return author information (list of persons).
1141  */
1142  QList<KAboutPerson> authors() const;
1143 
1144  /**
1145  * Returns a list of persons who contributed.
1146  * @return credit information (list of persons).
1147  */
1148  QList<KAboutPerson> credits() const;
1149 
1150  /**
1151  * Returns a list of translators.
1152  * @return translators information (list of persons)
1153  */
1154  QList<KAboutPerson> translators() const;
1155 
1156  /**
1157  * Returns a message about the translation team.
1158  * @return a message about the translation team
1159  */
1160  static QString aboutTranslationTeam();
1161 
1162  /**
1163  * Returns a list of components.
1164  * @return component information (list of components).
1165  * @since 5.84
1166  */
1167  QList<KAboutComponent> components() const;
1168 
1169  /**
1170  * Returns a translated, free form text.
1171  * @return the free form text (translated). Can be QString() if not set.
1172  */
1173  QString otherText() const;
1174 
1175  /**
1176  * Returns a list of licenses.
1177  *
1178  * @return licenses information (list of licenses)
1179  */
1180  QList<KAboutLicense> licenses() const;
1181 
1182  /**
1183  * Returns the copyright statement.
1184  * @return the copyright statement. Can be QString() if not set.
1185  */
1186  QString copyrightStatement() const;
1187 
1188  /**
1189  * Returns the plain text displayed around the list of authors instead
1190  * of the default message telling users to send bug reports to bugAddress().
1191  *
1192  * @return the plain text displayed around the list of authors instead
1193  * of the default message. Can be QString().
1194  */
1195  QString customAuthorPlainText() const;
1196 
1197  /**
1198  * Returns the rich text displayed around the list of authors instead
1199  * of the default message telling users to send bug reports to bugAddress().
1200  *
1201  * @return the rich text displayed around the list of authors instead
1202  * of the default message. Can be QString().
1203  */
1204  QString customAuthorRichText() const;
1205 
1206  /**
1207  * Returns whether custom text should be displayed around the list of
1208  * authors.
1209  *
1210  * @return whether custom text should be displayed around the list of
1211  * authors.
1212  */
1213  bool customAuthorTextEnabled() const;
1214 
1215  /**
1216  * Sets the custom text displayed around the list of authors instead
1217  * of the default message telling users to send bug reports to bugAddress().
1218  *
1219  * @param plainText The plain text.
1220  * @param richText The rich text.
1221  *
1222  * Setting both to parameters to QString() will cause no message to be
1223  * displayed at all. Call unsetCustomAuthorText() to revert to the default
1224  * message.
1225  */
1226  KAboutData &setCustomAuthorText(const QString &plainText, const QString &richText);
1227 
1228  /**
1229  * Clears any custom text displayed around the list of authors and falls
1230  * back to the default message telling users to send bug reports to
1231  * bugAddress().
1232  */
1233  KAboutData &unsetCustomAuthorText();
1234 
1235  /**
1236  * Configures the @p parser command line parser to provide an authors entry with
1237  * information about the developers of the application and an entry specifying the license.
1238  *
1239  * Additionally, it will set the description to the command line parser, will add the help
1240  * option and if the QApplication has a version set (e.g. via KAboutData::setApplicationData)
1241  * it will also add the version option.
1242  *
1243  * Since 5.16 it also adds an option to set the desktop file name.
1244  *
1245  * @returns true if adding the options was successful; otherwise returns false.
1246  *
1247  * @sa processCommandLine()
1248  */
1249  bool setupCommandLine(QCommandLineParser *parser);
1250 
1251  /**
1252  * Reads the processed @p parser and sees if any of the arguments are the ones set
1253  * up from setupCommandLine().
1254  *
1255  * @sa setupCommandLine()
1256  */
1257  void processCommandLine(QCommandLineParser *parser);
1258 
1259  /**
1260  * Sets the base name of the desktop entry for this application.
1261  *
1262  * This is the file name, without the full path and without extension,
1263  * of the desktop entry that represents this application according to
1264  * the freedesktop desktop entry specification (e.g. "org.kde.foo").
1265  *
1266  * A default desktop file name is constructed when the KAboutData
1267  * object is created, using the reverse domain name of the
1268  * organizationDomain() and the componentName() as they are at the time
1269  * of the KAboutData object creation.
1270  * Call this method to override that default name. Typically this is
1271  * done when also setOrganizationDomain(const QByteArray&) or setComponentName(const QString&)
1272  * need to be called to override the initial values.
1273  *
1274  * The desktop file name can also be passed to the application at runtime through
1275  * the @c desktopfile command line option which is added by setupCommandLine(QCommandLineParser*).
1276  * This is useful if an application supports multiple desktop files with different runtime
1277  * settings.
1278  *
1279  * @param desktopFileName The desktop file name of this application
1280  *
1281  * @sa desktopFileName()
1282  * @sa organizationDomain()
1283  * @sa componentName()
1284  * @sa setupCommandLine(QCommandLineParser*)
1285  * @since 5.16
1286  **/
1287  KAboutData &setDesktopFileName(const QString &desktopFileName);
1288 
1289  /**
1290  * @returns The desktop file name of this application (e.g. "org.kde.foo")
1291  * @sa setDesktopFileName(const QString&)
1292  * @since 5.16
1293  **/
1294  QString desktopFileName() const;
1295 
1296 private:
1297  friend void KCrash::defaultCrashHandler(int sig);
1298  // exported for KCrash, no other users intended
1299  static const KAboutData *applicationDataPointer();
1300 
1301 private:
1302  std::unique_ptr<class KAboutDataPrivate> const d;
1303 };
1304 
1305 Q_DECLARE_METATYPE(KAboutData)
1306 Q_DECLARE_METATYPE(KAboutLicense)
1307 Q_DECLARE_METATYPE(KAboutPerson)
1308 Q_DECLARE_METATYPE(KAboutComponent)
1309 
1310 #endif
NameFormat
Format of the license name.
Definition: kaboutdata.h:215
KAboutComponent & operator=(const KAboutComponent &other)
Assignment operator.
KCRASH_EXPORT void defaultCrashHandler(int signal)
LicenseKey
Describes the license of the software; for more information see: https://spdx.org/licenses/.
Definition: kaboutdata.h:194
This class is used to store information about a third party component.
Definition: kaboutdata.h:371
KAboutData & addAuthor(const QString &name, const QString &task, const QString &emailAddress, const QString &webAddress, const QString &kdeStoreUsername)
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: kaboutdata.h:715
This class is used to store information about a person or developer.
Definition: kaboutdata.h:61
VersionRestriction
Whether later versions of the license are allowed.
Definition: kaboutdata.h:224
This class is used to store information about a license.
Definition: kaboutdata.h:180
@ Unknown
Unknown license.
Definition: kaboutdata.h:197
KAboutData & addCredit(const QString &name, const QString &task, const QString &emailAddress, const QString &webAddress, const QString &kdeStoreUsername)
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition: kaboutdata.h:751
Holds information needed by the "About" box and other classes.
Definition: kaboutdata.h:536
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 04:01:08 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.