tdelibs/tdecore/kaboutdata.h

/*
 * This file is part of the KDE Libraries
 * Copyright (C) 2000 Espen Sand (espen@kde.org)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 *
 */

#include <tqvaluelist.h>
#include <tqstring.h>
#include <tqimage.h>
#include <klocale.h>

#ifndef _KABOUTDATA_H_
#define _KABOUTDATA_H_

class KAboutPersonPrivate;
class KAboutDataPrivate;

/**
 * This structure is used to store information about a person or developer.
 * It can store the person's name, a task, an email address and a
 * link to a home page. This class is intended for use in the
 * KAboutData class, but it can be used elsewhere as well.
 * Normally you should at least define the person's name.
 *
 * Example Usage within a main():
 *
 * \code
 *   KAboutData about("khello", I18N_NOOP("KHello"), "0.1",
 *                   I18N_NOOP("A KDE version of Hello, world!"),
 *                   KAboutData::License_LGPL,
 *                   I18N_NOOP("Copyright (c) 2003 Developer"));
 *
 *   about.addAuthor("Joe Developer", I18N_NOOP("developer"), "joe@host.com", 0);
 *   about.addCredit("Joe User", I18N_NOOP("A lot of bug reports"),
 *                   "joe.user@host.org", 0);
 *   KCmdLineArgs::init(argc, argv, &about);
 * \endcode
 */
class TDECORE_EXPORT KAboutPerson
{
public:
    /**
     * Convenience constructor
     *
     * @param name The name of the person.
     *
     * @param task The task of this person. This string should be
     *              marked for translation, e.g.
     *              I18N_NOOP("Task description....")
     *
     * @param emailAddress The email address of the person.
     *
     * @param webAddress Home page of the person.
     */
    KAboutPerson( const char *name, const char *task,
                  const char *emailAddress, const char *webAddress )
    {
      mName = name;
      mTask = task;
      mEmailAddress = emailAddress;
      mWebAddress = webAddress;
    }
    /**
     * @internal
     * Don't use. Required by QValueList
     */
    KAboutPerson() {}

    /**
     * The person's name
     * @return the person's name (can be TQString::null, if it has been
     *           constructed with a null name)
     */
    TQString name() const;

    /**
     * The person's task
     * @return the person's task (can be TQString::null, if it has been
     *           constructed with a null task)
     */
    TQString task() const;

    /**
     * The person's email address
     * @return the person's email address (can be TQString::null, if it has been
     *           constructed with a null email)
     */
    TQString emailAddress() const;

    /**
     * The home page or a relevant link
     * @return the persons home page (can be TQString::null, if it has been
     *           constructed with a null home page)
     */
    TQString webAddress() const;

private:
    const char *mName;
    const char *mTask;
    const char *mEmailAddress;
    const char *mWebAddress;

    KAboutPersonPrivate *d;
};

class KAboutTranslatorPrivate;
/**
 * This structure is used to store information about a translator.
 * It can store the translator's name and an email address.
 * This class is intended for use in the KAboutData class,
 * but it can be used elsewhere as well.
 * Normally you should at least define the translator's name.
 *
 * It's not possible to use KAboutPerson for this, because
 * KAboutPerson stores internally only const char* pointers, but the
 * translator information is generated dynamically from the translation
 * of a dummy string.
*/
class TDECORE_EXPORT KAboutTranslator
{
public:
    /**
     * Convenience constructor
     *
     * @param name The name of the person.
     *
     * @param emailAddress The email address of the person.
     */
    KAboutTranslator(const TQString & name=TQString::null,
                     const TQString & emailAddress=TQString::null);

    /**
     * The translator's name
     * @return the translators's name (can be TQString::null, if it has been
     *           constructed with a null name)
     */
    TQString name() const;

    /**
     * The translator's email
     * @return the translator's email address (can be TQString::null, if it has been
     *           constructed with a null email)
     */
    TQString emailAddress() const;

private:
    TQString mName;
    TQString mEmail;
    KAboutTranslatorPrivate* d;
};


/**
 * This class is used to store information about a program. It can store
 * such values as version number, program name, home page, email address
 * for bug reporting, multiple authors and contributors
 * (using KAboutPerson), license and copyright information.
 *
 * Currently, the values set here are shown by the "About" box
 * (see KAboutDialog), used by the bug report dialog (see KBugReport),
 * and by the help shown on command line (see KCmdLineArgs).
 *
 * @short Holds information needed by the "About" box and other
 * classes.
 * @author Espen Sand (espen@kde.org), David Faure (faure@kde.org)
 */
class TDECORE_EXPORT KAboutData
{
  public:
  /**
   * Descibes the license of the software.
   */
    enum LicenseKey
    {
      License_Custom = -2,
      License_File = -1,
      License_Unknown = 0,
      License_GPL  = 1,
      License_GPL_V2 = 1,
      License_LGPL = 2,
      License_LGPL_V2 = 2,
      License_BSD  = 3,
      License_Artistic = 4,
      License_QPL = 5,
      License_QPL_V1_0 = 5
    };

  public:
    /**
     * Constructor.
     *
     * @param appName The program name used internally. Example: "kedit"
     *
     * @param programName A displayable program name string. This string
     *        should be marked for translation. Example: I18N_NOOP("KEdit")
     *
     * @param version The program version string.
     *
     * @param shortDescription A short description of what the program does.
     *        This string should be marked for translation.
     *        Example: I18N_NOOP("A simple text editor.")
     *
     * @param licenseType The license identifier. Use setLicenseText if
     *        you use a license not predefined here.
     *
     * @param copyrightStatement A copyright statement, that can look like this:
     *        "(c) 1999-2000, Name". The string specified here is not modified
     *        in any manner. The author information from addAuthor is not
     *        used.
     *
     * @param text Some free form text, that can contain any kind of
     *        information. The text can contain newlines. This string
     *        should be marked for translation.
     *
     * @param homePageAddress The program homepage string.
     *        Start the address with "http://". "http://some.domain" is
     *        is correct, "some.domain" is not.
     *
     * @param bugsEmailAddress The bug report email address string.
     *        This defaults to the kde.org bug system.
     *
     */
    KAboutData( const char *appName,
                const char *programName,
		const char *version,
		const char *shortDescription = 0,
		int licenseType = License_Unknown,
		const char *copyrightStatement = 0,
		const char *text = 0,
		const char *homePageAddress = 0,
		const char *bugsEmailAddress = "http://bugs.trinitydesktop.org"
		);

     ~KAboutData();

    /**
     * Defines an author. You can call this function as many times you
     * need. Each entry is appended to a list. The person in the first entry
     * is assumed to be the leader of the project.
     *
     * @param name The developer's name in UTF-8 encoding.
     *
     * @param task What the person is responsible for. This text can contain
     *             newlines. It should be marked for translation like this:
     *             I18N_NOOP("Task description..."). Can be 0.
     *
     * @param emailAddress An Email address where the person can be reached.
     *                     Can be 0.
     *
     * @param webAddress The person's homepage or a relevant link.
     *        Start the address with "http://". "http://some.domain" is
     *        correct, "some.domain" is not. Can be 0.
     *
     */
    void addAuthor( const char *name,
		    const char *task=0,
		    const char *emailAddress=0,
		    const char *webAddress=0 );

    /**
     * Defines a person that deserves credit. You can call this function
     * as many times you need. Each entry is appended to a list.
     *
     * @param name The person's name in UTF-8 encoding.
     *
     * @param task What the person has done to deserve the honor. The
     *        text can contain newlines. It should be marked for
     *        translation like this: I18N_NOOP("Task description...")
     *        Can be 0.
     *
     * @param emailAddress An Email address when the person can be reached.
     *        Can be 0.
     *
     * @param webAddress The person's homepage or a relevant link.
     *        Start the address with "http://". "http://some.domain" is
     *        is correct, "some.domain" is not. Can be 0.
     *
     */
    void addCredit( const char *name,
                    const char *task=0,
		    const char *emailAddress=0,
		    const char *webAddress=0 );

    /**
     * Sets the name of the translator of the gui. Since this depends
     * on the language, just use a dummy text marked for translation.
     *
     * For example:
     * \code
     * setTranslator(I18N_NOOP("_: NAME OF TRANSLATORS\\nYour names")
     * ,I18N_NOOP("_: EMAIL OF TRANSLATORS\\nYour emails"));
     * \endcode
     *
     * The translator can then translate this dummy text with his name
     * or with a list of names separated with ",".
     * If there is no translation or the application is used with the
     * default language, this function call is ignored.
     *
     * Note: If you are using the default KDE automake environment,
     * there is no need to use this function, because the two
     * default strings above are added to the applications po file
     * automatically.
     *
     * @param name the name of the translator
     * @param emailAddress the email address of the translator
     * @see KAboutTranslator
     */
    void setTranslator(const char* name, const char* emailAddress);

    /**
     * Defines a license text.
     *
     * The text will be translated if it got marked for
     * translations with the I18N_NOOP() macro.
     *
     * Example:
     * \code
     * setLicenseText( I18N_NOOP("This is my license"));
     * \endcode
     *
     * NOTE: No copy of the text is made.
     *
     * @param license The license text in utf8 encoding.
     */
    void setLicenseText( const char *license );

    /**
     * Defines a license text.
     *
     * @param file File containing the license text.
     */
    void setLicenseTextFile( const TQString &file );

    /**
     * Defines the program name used internally.
     *
     * @param appName The application name. Example: "kate".
     */
    void setAppName( const char *appName );
    
    /**
     * Defines the displayable program name string.
     *
     * @param programName The program name. This string should be
     *        marked for translation.
     *        Example: I18N_NOOP("Advanced Text Editor").
     * @since 3.2
     */
    void setProgramName( const char* programName );

    /**
     * Defines the program logo.
     * Use this if you need to have application logo 
     * in AboutData other than application icon.
     *
     * @param image logo image.
     * @see programLogo()
     * @since 3.4
    */
    void setProgramLogo(const TQImage& image);

    /**
     * Defines the program version string.
     *
     * @param version The program version.
     */
    void setVersion( const char* version );
    
    /**
     * Defines a short description of what the program does.
     *
     * @param shortDescription The program description This string should be marked
     *        for translation. Example: I18N_NOOP("An advanced text editor
     *        with syntax highlithing support.").
     */
    void setShortDescription( const char *shortDescription );
    
    /**
     * Defines the license identifier.
     *
     * @param licenseKey The license identifier.
     */
    void setLicense( LicenseKey licenseKey);
    
    /**
     * Defines the copyright statement to show when displaying the license.
     *
     * @param copyrightStatement A copyright statement, that can look like
     *        this: "(c) 1999-2000, Name". The string specified here is not
     *        modified in any manner. The author information from addAuthor
     *        is not used.
     */
    void setCopyrightStatement( const char *copyrightStatement );
    
    /**
     * Defines the additional text to show in the about dialog.
     *
     * @param otherText Some free form text, that can contain any kind of
     *        information. The text can contain newlines. This string
     *        should be marked for translation.
     */
    void setOtherText( const char *otherText );
    
    /**
     * Defines the program homepage.
     *
     * @param homepage The program homepage string.
     *        Start the address with "http://". "http://kate.kde.org" is
     *        is correct, "kde.kde.org" is not.
     */
    void setHomepage( const char *homepage );
    
    /**
     * Defines the address where bug reports should be sent.
     *
     * @param bugAddress The bug report email address string.
     *        This defaults to the kde.org bug system.
     */
    void setBugAddress( const char *bugAddress );
    
    /**
     * Defines the product name wich will be used in the KBugReport dialog.
     * By default it's the appName, but you can overwrite it here to provide
     * support for special components e.g. 'product/component' like
     * 'kontact/summary'.
     *
     * @param name The name of product
     */
    void setProductName( const char *name );

    /**
     * Returns the application's internal name.
     * @return the internal program name.
     */
    const char *appName() const;

    /**
     * Returns the application's product name, which will be used in KBugReport
     * dialog. By default it returns appName(), otherwise the one which is set
     * with setProductName()
     * 
     * @return the product name.
     */
    const char *productName() const;

    /**
     * Returns the translated program name.
     * @return the program name (translated).
     */
    TQString programName() const;

    /**
     * @internal
     */
    const char* internalProgramName() const;
    /**
     * @internal
     */
    void translateInternalProgramName() const;

    /**
     * Returns the program logo image. 
     * @return the program logo data or null image if there is 
     * no custom application logo defined.
     * @since 3.4
     */
    TQImage programLogo() const;

    /**
     * Returns the program's version.
     * @return the version string.
     */
    TQString version() const;

    /**
     * @internal
     */
    const char* internalVersion() const { return mVersion; }

    /**
     * Returns a short, translated description.
     * @return the short description (translated). Can be
     *         TQString::null if not set.
     */
    TQString shortDescription() const;

    /**
     * Returns the application homepage.
     * @return the application homepage URL. Can be TQString::null if
     *         not set.
     */
    TQString homepage() const;

    /**
     * Returns the email address for bugs.
     * @return the email address where to report bugs.
     */
    TQString bugAddress() const;
    
    /**
     * @internal
     */
    const char* internalBugAddress() const { return mBugEmailAddress; }

    /**
     * Returns a list of authors.
     * @return author information (list of persons).
     */
    const TQValueList<KAboutPerson> authors() const;

    /**
     * Returns a list of persons who contributed.
     * @return credit information (list of persons).
     */
    const TQValueList<KAboutPerson> credits() const;

    /**
     * Returns a list of translators.
     * @return translators information (list of persons)
     */
    const TQValueList<KAboutTranslator> translators() const;

    /**
     * Returns a message about the translation team.
     * @return a message about the translation team
     */
    static TQString aboutTranslationTeam();

    /**
     * Returns a translated, free form text.
     * @return the free form text (translated). Can be TQString::null if not set.
     */
    TQString otherText() const;

    /**
     * Returns the license. If the licenseType argument of the constructor has been
     * used, any text defined by setLicenseText is ignored,
     * and the standard text for the chosen license will be returned.
     *
     * @return The license text.
     */
    TQString license() const;

    /**
     * Returns the copyright statement.
     * @return the copyright statement. Can be TQString::null if not set.
     */
    TQString copyrightStatement() const;

    /**
     * Returns the plain text displayed around the list of authors instead
     * of the default message telling users to send bug reports to bugAddress().
     *
     * @return the plain text displayed around the list of authors instead
     *         of the default message.  Can be TQString::null.
     */
    TQString customAuthorPlainText() const;

    /**
     * Returns the rich text displayed around the list of authors instead
     * of the default message telling users to send bug reports to bugAddress().
     *
     * @return the rich text displayed around the list of authors instead
     *         of the default message.  Can be TQString::null.
     */
    TQString customAuthorRichText() const;

    /**
     * Returns whether custom text should be displayed around the list of
     * authors.
     *
     * @return whether custom text should be displayed around the list of
     *         authors.
     */
    bool customAuthorTextEnabled() const;
    
    /**
     * Sets the custom text displayed around the list of authors instead
     * of the default message telling users to send bug reports to bugAddress().
     *
     * @param plainText The plain text.
     * @param richText The rich text.
     *
     * Both parameters can be TQString::null to not display any message at
     * all.  Call unsetCustomAuthorText() to revert to the default mesage.
     */
    void setCustomAuthorText(const TQString &plainText, const TQString &richText);
    
    /**
     * Clears any custom text displayed around the list of authors and falls
     * back to the default message telling users to send bug reports to
     * bugAddress().
     */
    void unsetCustomAuthorText();
    
  private:
    const char *mAppName;
    const char *mProgramName;
    const char *mVersion;
    const char *mShortDescription;
    int mLicenseKey;
    const char *mCopyrightStatement;
    const char *mOtherText;
    const char *mHomepageAddress;
    const char *mBugEmailAddress;
    TQValueList<KAboutPerson> mAuthorList;
    TQValueList<KAboutPerson> mCreditList;
    const char *mLicenseText;

    KAboutDataPrivate *d;
};

#endif