kaboutdata.h

/*
    This file is part of the KDE Libraries

    SPDX-FileCopyrightText: 2000 Espen Sand <[email protected]>
    SPDX-FileCopyrightText: 2008 Friedrich W. H. Kossebau <[email protected]>
    SPDX-FileCopyrightText: 2010 Teo Mrnjavac <[email protected]>
    SPDX-FileCopyrightText: 2013 David Faure <[email protected]>
    SPDX-FileCopyrightText: 2017 Harald Sitter <[email protected]>

    SPDX-License-Identifier: LGPL-2.0-or-later
*/

#ifndef KABOUTDATA_H
#define KABOUTDATA_H

#include <kcoreaddons_export.h>
#include <QString>
#include <QSharedDataPointer>
#include <QVariant>
#include <qcontainerfwd.h>

class QCommandLineParser;
class QJsonObject;
class KAboutData;
class KPluginMetaData;
namespace KCrash
{
Q_DECL_IMPORT void defaultCrashHandler(int sig);
}

class KCOREADDONS_EXPORT KAboutPerson
{
    Q_GADGET
    Q_PROPERTY(QString name READ name CONSTANT)
    Q_PROPERTY(QString task READ task CONSTANT)
    Q_PROPERTY(QString emailAddress READ emailAddress CONSTANT)
    Q_PROPERTY(QString webAddress READ webAddress CONSTANT)
    Q_PROPERTY(QString ocsUsername READ ocsUsername CONSTANT)
    friend class KAboutData;
public:
    explicit KAboutPerson(const QString &name = QString(),
                          const QString &task = QString(),
                          const QString &emailAddress = QString(),
                          const QString &webAddress = QString(),
                          const QString &ocsUsername = QString());

    KAboutPerson(const KAboutPerson &other);

    ~KAboutPerson();

    KAboutPerson &operator=(const KAboutPerson &other);

    QString name() const;

    QString task() const;

    QString emailAddress() const;

    QString webAddress() const;

    QString ocsUsername() const;

    static KAboutPerson fromJSON(const QJsonObject &obj);

private:
    explicit KAboutPerson(const QString &name, const QString &email, bool disambiguation);

    class Private;
    Private *const d;
};

class KCOREADDONS_EXPORT KAboutLicense
{
    Q_GADGET
    Q_PROPERTY(QString name READ name CONSTANT)
    Q_PROPERTY(QString text READ text CONSTANT)
    Q_PROPERTY(KAboutLicense::LicenseKey key READ key CONSTANT)
    Q_PROPERTY(QString spdx READ spdx CONSTANT)
    friend class KAboutData;
public:

    enum LicenseKey {
        Custom = -2,
        File = -1,
        Unknown = 0,
        GPL  = 1,
        GPL_V2 = 1,
        LGPL = 2,
        LGPL_V2 = 2,
        BSDL = 3,
        Artistic = 4,
        QPL = 5,
        QPL_V1_0 = 5,
        GPL_V3 = 6,
        LGPL_V3 = 7,
        LGPL_V2_1 = 8 
    };
    Q_ENUM(LicenseKey)

    
    enum NameFormat {
        ShortName,
        FullName
    };
    Q_ENUM(NameFormat)

    
    enum VersionRestriction {
        OnlyThisVersion,
        OrLaterVersions
    };
    Q_ENUM(VersionRestriction)

    
    explicit KAboutLicense();

    KAboutLicense(const KAboutLicense &other);

    ~KAboutLicense();

    KAboutLicense &operator=(const KAboutLicense &other);

    QString text() const;

    QString name(KAboutLicense::NameFormat formatName = ShortName) const;

    KAboutLicense::LicenseKey key() const;

    QString spdx() const;

    static KAboutLicense byKeyword(const QString &keyword);

private:
    explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType,
                           enum KAboutLicense::VersionRestriction versionRestriction,
                           const KAboutData *aboutData);
    explicit KAboutLicense(enum KAboutLicense::LicenseKey licenseType, const KAboutData *aboutData);
    explicit KAboutLicense(const KAboutData *aboutData);
    void setLicenseFromPath(const QString &pathToFile);
    void setLicenseFromText(const QString &licenseText);

    class Private;
    QSharedDataPointer<Private> d;
};

class KCOREADDONS_EXPORT KAboutData
{
    Q_GADGET
    Q_PROPERTY(QString displayName READ displayName CONSTANT)
    Q_PROPERTY(QString productName READ productName CONSTANT)
    Q_PROPERTY(QString componentName READ componentName CONSTANT)
    Q_PROPERTY(QVariant programLogo READ programLogo CONSTANT)
    Q_PROPERTY(QString shortDescription READ shortDescription CONSTANT)
    Q_PROPERTY(QString homepage READ homepage CONSTANT)
    Q_PROPERTY(QString bugAddress READ bugAddress CONSTANT)
    Q_PROPERTY(QString version READ version CONSTANT)
    Q_PROPERTY(QString otherText READ otherText CONSTANT)
    Q_PROPERTY(QVariantList authors READ authorsVariant CONSTANT) //constant in practice as addAuthor is not exposed to Q_GADGET
    Q_PROPERTY(QVariantList credits READ creditsVariant CONSTANT)
    Q_PROPERTY(QVariantList translators READ translatorsVariant CONSTANT)
    Q_PROPERTY(QVariantList licenses READ licensesVariant CONSTANT)
    Q_PROPERTY(QString copyrightStatement READ copyrightStatement CONSTANT)
    Q_PROPERTY(QString desktopFileName READ desktopFileName CONSTANT)
public:

    static KAboutData applicationData();

    static void setApplicationData(const KAboutData &aboutData);

// BUILD, not ENABLE, as producers need to support the registry for backward-compat
#if KCOREADDONS_BUILD_DEPRECATED_SINCE(5, 76)

    KCOREADDONS_DEPRECATED_VERSION(5, 76, "See API docs")
    static void registerPluginData(const KAboutData &aboutData);
#endif

#if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 76)

    KCOREADDONS_DEPRECATED_VERSION(5, 76, "See API docs")
    static KAboutData *pluginData(const QString &componentName);
#endif

#if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 65)

    KCOREADDONS_DEPRECATED_VERSION(5, 65, "See API docs")
    static KAboutData fromPluginMetaData(const KPluginMetaData &plugin);
#endif

public:
    // KF6: remove constructor that includes catalogName, and put default
    //      values back in for shortDescription and licenseType
    KAboutData(const QString &componentName,
               const QString &displayName,
               const QString &version,
               const QString &shortDescription,
               enum KAboutLicense::LicenseKey licenseType,
               const QString &copyrightStatement = QString(),
               const QString &otherText = QString(),
               const QString &homePageAddress = QString(),
               const QString &bugAddress = QStringLiteral("[email protected]")
              );

    explicit KAboutData(const QString &componentName = {},
               const QString &displayName = {},
               const QString &version = {}
              );

    KAboutData(const KAboutData &other);

    KAboutData &operator=(const KAboutData &other);

    ~KAboutData();

    KAboutData &addAuthor(const QString &name,
                          const QString &task = QString(),
                          const QString &emailAddress = QString(),
                          const QString &webAddress = QString(),
                          const QString &ocsUsername = QString());

    KAboutData &addCredit(const QString &name,
                          const QString &task = QString(),
                          const QString &emailAddress = QString(),
                          const QString &webAddress = QString(),
                          const QString &ocsUsername = QString());

    KAboutData &setTranslator(const QString &name,
                              const QString &emailAddress);

    KAboutData &setLicenseText(const QString &license);

    KAboutData &addLicenseText(const QString &license);

    KAboutData &setLicenseTextFile(const QString &file);

    KAboutData &addLicenseTextFile(const QString &file);

    KAboutData &setComponentName(const QString &componentName);

    KAboutData &setDisplayName(const QString &displayName);

#if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 2)

    KCOREADDONS_DEPRECATED_VERSION(5, 2, "Use QApplication::setWindowIcon")
    KAboutData &setProgramIconName(const QString &iconName);
#endif

    KAboutData &setProgramLogo(const QVariant &image);

    KAboutData &setOcsProvider(const QString &providerUrl);

    KAboutData &setVersion(const QByteArray &version);

    KAboutData &setShortDescription(const QString &shortDescription);

    KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey);

    KAboutData &setLicense(KAboutLicense::LicenseKey licenseKey,
                           KAboutLicense::VersionRestriction versionRestriction);

    KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey);

    KAboutData &addLicense(KAboutLicense::LicenseKey licenseKey,
                           KAboutLicense::VersionRestriction versionRestriction);

    KAboutData &setCopyrightStatement(const QString &copyrightStatement);

    KAboutData &setOtherText(const QString &otherText);

    KAboutData &setHomepage(const QString &homepage);

    KAboutData &setBugAddress(const QByteArray &bugAddress);

    KAboutData &setOrganizationDomain(const QByteArray &domain);

    KAboutData &setProductName(const QByteArray &name);

    QString componentName() const;

    QString productName() const;

    QString displayName() const;

    QString organizationDomain() const;

    const char *internalProgramName() const;

// Not using KCOREADDONS_ENABLE_DEPRECATED_SINCE because KXmlGui and KConfigWidgets need this, for compat
#if KCOREADDONS_BUILD_DEPRECATED_SINCE(5, 2)

    KCOREADDONS_DEPRECATED_VERSION(5, 2, "Use QApplication::windowIcon")
    QString programIconName() const;
#endif

    QVariant programLogo() const;

    QString ocsProviderUrl() const;

    QString version() const;

    const char *internalVersion() const;

    QString shortDescription() const;

    QString homepage() const;

    QString bugAddress() const;

    const char *internalBugAddress() const;

    QList<KAboutPerson> authors() const;

    QList<KAboutPerson> credits() const;

    QList<KAboutPerson> translators() const;

    static QString aboutTranslationTeam();

    QString otherText() const;

    QList<KAboutLicense> licenses() const;

    QString copyrightStatement() const;

    QString customAuthorPlainText() const;

    QString customAuthorRichText() const;

    bool customAuthorTextEnabled() const;

    KAboutData &setCustomAuthorText(const QString &plainText,
                                    const QString &richText);

    KAboutData &unsetCustomAuthorText();

    bool setupCommandLine(QCommandLineParser *parser);

    void processCommandLine(QCommandLineParser *parser);

    KAboutData &setDesktopFileName(const QString &desktopFileName);

    QString desktopFileName() const;

private:
    QVariantList licensesVariant() const;
    QVariantList authorsVariant() const;
    QVariantList creditsVariant() const;
    QVariantList translatorsVariant() const;

    friend void KCrash::defaultCrashHandler(int sig);
    static const KAboutData *applicationDataPointer();

    class Private;
    Private *const d;
};

Q_DECLARE_METATYPE(KAboutData)
Q_DECLARE_METATYPE(KAboutLicense)
Q_DECLARE_METATYPE(KAboutPerson)

#endif