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