KCoreAddons

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

KDE's Doxygen guidelines are available online.