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

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