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