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 | |
25 | class QCommandLineParser; |
26 | class QJsonObject; |
27 | class KAboutData; |
28 | namespace KCrash |
29 | { |
30 | #ifdef KCOREADDONS_STATIC |
31 | void defaultCrashHandler(int sig); |
32 | #else |
33 | Q_DECL_IMPORT void defaultCrashHandler(int sig); |
34 | #endif |
35 | } |
36 | |
37 | /** |
38 | * This class is used to store information about a person or developer. |
39 | * It can store the person's name, a task, an email address and a |
40 | * link to a home page. This class is intended for use in the |
41 | * KAboutData class, but it can be used elsewhere as well. |
42 | * Normally you should at least define the person's name. |
43 | * Creating a KAboutPerson object by yourself is relatively useless, |
44 | * but the KAboutData methods KAboutData::authors() and KAboutData::credits() |
45 | * return lists of KAboutPerson data objects which you can examine. |
46 | * |
47 | * Example usage within a main(), retrieving the list of people involved |
48 | * with a program and re-using data from one of them: |
49 | * |
50 | * @code |
51 | * KAboutData about("khello", i18n("KHello"), "0.1", |
52 | * i18n("A KDE version of Hello, world!"), |
53 | * KAboutLicense::LGPL, |
54 | * i18n("Copyright (C) 2014 Developer")); |
55 | * |
56 | * about.addAuthor(i18n("Joe Developer"), i18n("developer"), "joe@host.com", 0); |
57 | * QList<KAboutPerson> people = about.authors(); |
58 | * about.addCredit(people[0].name(), people[0].task()); |
59 | * @endcode |
60 | */ |
61 | class KCOREADDONS_EXPORT KAboutPerson |
62 | { |
63 | Q_GADGET |
64 | Q_PROPERTY(QString name READ name CONSTANT) |
65 | Q_PROPERTY(QString task READ task CONSTANT) |
66 | Q_PROPERTY(QString emailAddress READ emailAddress CONSTANT) |
67 | Q_PROPERTY(QString webAddress READ webAddress CONSTANT) |
68 | Q_PROPERTY(QUrl avatarUrl READ avatarUrl CONSTANT) |
69 | friend class KAboutData; |
70 | friend class KAboutDataPrivate; |
71 | |
72 | public: |
73 | /** |
74 | * Convenience constructor |
75 | * |
76 | * @param name The name of the person. |
77 | * |
78 | * @param task The task of this person. |
79 | * |
80 | * @param emailAddress The email address of the person. |
81 | * |
82 | * @param webAddress Home page of the person. |
83 | * |
84 | * @param avatarUrl URL to the avatar of the person, since 6.0 |
85 | * |
86 | * @p name default argument @since 5.53 |
87 | */ |
88 | explicit KAboutPerson(const QString &name = QString(), |
89 | const QString &task = QString(), |
90 | const QString &emailAddress = QString(), |
91 | const QString &webAddress = QString(), |
92 | const QUrl &avatarUrl = QUrl()); |
93 | |
94 | /** |
95 | * Copy constructor. Performs a deep copy. |
96 | * @param other object to copy |
97 | */ |
98 | KAboutPerson(const KAboutPerson &other); |
99 | |
100 | ~KAboutPerson(); |
101 | |
102 | /** |
103 | * Assignment operator. Performs a deep copy. |
104 | * @param other object to copy |
105 | */ |
106 | KAboutPerson &operator=(const KAboutPerson &other); |
107 | |
108 | /** |
109 | * The person's name |
110 | * @return the person's name (can be QString(), if it has been |
111 | * constructed with an empty name) |
112 | */ |
113 | QString name() const; |
114 | |
115 | /** |
116 | * The person's task |
117 | * @return the person's task (can be QString(), if it has been |
118 | * constructed with an empty task) |
119 | */ |
120 | QString task() const; |
121 | |
122 | /** |
123 | * The person's email address |
124 | * @return the person's email address (can be QString(), if it has been |
125 | * constructed with an empty email) |
126 | */ |
127 | QString emailAddress() const; |
128 | |
129 | /** |
130 | * The home page or a relevant link |
131 | * @return the persons home page (can be QString(), if it has been |
132 | * constructed with an empty home page) |
133 | */ |
134 | QString webAddress() const; |
135 | |
136 | /** |
137 | * @return an URL pointing to the user's avatar |
138 | * @since 6.0 |
139 | */ |
140 | QUrl avatarUrl() const; |
141 | |
142 | /** |
143 | * Creates a @c KAboutPerson from a JSON object with the following structure: |
144 | * |
145 | * Key | Accessor |
146 | * -----------| ---------------------------- |
147 | * Name | name() |
148 | * Email | emailAddress() |
149 | * Task | task() |
150 | * Website | webAddress() |
151 | * AvatarUrl | avatarUrl() |
152 | * |
153 | * The @c Name and @c Task key are translatable (by using e.g. a "Task[de_DE]" key) |
154 | * The AvatarUrl exists since version 6.0 |
155 | * |
156 | * @since 5.18 |
157 | */ |
158 | static KAboutPerson fromJSON(const QJsonObject &obj); |
159 | |
160 | private: |
161 | /** |
162 | * @internal Used by KAboutData to construct translator data. |
163 | */ |
164 | KCOREADDONS_NO_EXPORT explicit KAboutPerson(const QString &name, const QString &email, bool disambiguation); |
165 | |
166 | private: |
167 | QSharedDataPointer<class KAboutPersonPrivate> d; |
168 | }; |
169 | |
170 | Q_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 | */ |
182 | class 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 | |
192 | public: |
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 | |
315 | private: |
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 | |
339 | private: |
340 | QSharedDataPointer<class KAboutLicensePrivate> d; |
341 | }; |
342 | |
343 | Q_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 | */ |
374 | class 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 | |
385 | public: |
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 | |
474 | private: |
475 | QSharedDataPointer<class KAboutComponentPrivate> d; |
476 | }; |
477 | |
478 | Q_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 | */ |
541 | class 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) |
560 | public: |
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 | |
593 | public: |
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 ©rightStatement = 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 ©rightStatement); |
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 | |
1301 | private: |
1302 | friend void KCrash::defaultCrashHandler(int sig); |
1303 | // exported for KCrash, no other users intended |
1304 | static const KAboutData *applicationDataPointer(); |
1305 | |
1306 | private: |
1307 | std::unique_ptr<class KAboutDataPrivate> const d; |
1308 | }; |
1309 | |
1310 | #endif |
1311 | |