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

source code of kcoreaddons/src/lib/kaboutdata.h