KDECore

KAboutData Class Reference

#include <kaboutdata.h>

Detailed Description

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).

Note:: Instead of the more usual i18n calls, for translatable text the ki18n calls are used to produce KLocalizedStrings, which can delay the translation lookup. This is necessary because the translation catalogs are usualy not yet initialized at the point where KAboutData is constructed.

Holds information needed by the "About" box and other classes.

Author:: Espen Sand (espen@kde.org), David Faure (faure@kde.org)

Definition at line 157 of file kaboutdata.h.


Public Types
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 }
enum	NameFormat { ShortName, FullName }
Public Member Functions
	KAboutData (const QByteArray &appName, const QByteArray &catalogName, const KLocalizedString &programName, const QByteArray &version, const KLocalizedString &shortDescription=KLocalizedString(), enum LicenseKey licenseType=License_Unknown, const KLocalizedString &copyrightStatement=KLocalizedString(), const KLocalizedString &text=KLocalizedString(), const QByteArray &homePageAddress=QByteArray(), const QByteArray &bugsEmailAddress="submit@bugs.kde.org")
	KAboutData (const KAboutData &other)
KAboutData &	operator= (const KAboutData &other)
	~KAboutData ()
KAboutData &	addAuthor (const KLocalizedString &name, const KLocalizedString &task=KLocalizedString(), const QByteArray &emailAddress=QByteArray(), const QByteArray &webAddress=QByteArray())
KAboutData &	addCredit (const KLocalizedString &name, const KLocalizedString &task=KLocalizedString(), const QByteArray &emailAddress=QByteArray(), const QByteArray &webAddress=QByteArray())
KAboutData &	setTranslator (const KLocalizedString &name, const KLocalizedString &emailAddress)
KAboutData &	setLicenseText (const KLocalizedString &license)
KAboutData &	setLicenseTextFile (const QString &file)
KAboutData &	setAppName (const QByteArray &appName)
KAboutData &	setProgramName (const KLocalizedString &programName)
KAboutData &	setProgramLogo (const QVariant &image)
KAboutData &	setVersion (const QByteArray &version)
KAboutData &	setShortDescription (const KLocalizedString &shortDescription)
KAboutData &	setCatalogName (const QByteArray &catalogName)
KAboutData &	setLicense (LicenseKey licenseKey)
KAboutData &	setCopyrightStatement (const KLocalizedString &copyrightStatement)
KAboutData &	setOtherText (const KLocalizedString &otherText)
KAboutData &	setHomepage (const QByteArray &homepage)
KAboutData &	setBugAddress (const QByteArray &bugAddress)
KAboutData &	setOrganizationDomain (const QByteArray &domain)
KAboutData &	setProductName (const QByteArray &name)
QString	appName () const
QString	productName () const
QString	programName () const
QString	organizationDomain () const
const char *	internalProgramName () const
void	translateInternalProgramName () const
QVariant	programLogo () const
QString	version () const
const char *	internalVersion () const
QString	shortDescription () const
QString	catalogName () const
QString	homepage () const
QString	bugAddress () const
const char *	internalBugAddress () const
QList< KAboutPerson >	authors () const
QList< KAboutPerson >	credits () const
QList< KAboutPerson >	translators () const
QString	otherText () const
QString	license () const
QString	licenseName (NameFormat formatName) const
QString	copyrightStatement () const
QString	customAuthorPlainText () const
QString	customAuthorRichText () const
bool	customAuthorTextEnabled () const
KAboutData &	setCustomAuthorText (const KLocalizedString &plainText, const KLocalizedString &richText)
KAboutData &	unsetCustomAuthorText ()
Static Public Member Functions
static QString	aboutTranslationTeam ()

Member Enumeration Documentation

enum KAboutData::LicenseKey

Descibes the license of the software.

Enumerator:

License_Custom
License_File
License_Unknown
License_GPL
License_GPL_V2
License_LGPL
License_LGPL_V2
License_BSD
License_Artistic
License_QPL
License_QPL_V1_0

Definition at line 163 of file kaboutdata.h.

enum KAboutData::NameFormat

Format of the license name.

Enumerator:

ShortName
FullName

Definition at line 181 of file kaboutdata.h.

Constructor & Destructor Documentation

KAboutData::KAboutData	(	const QByteArray &	appName,
		const QByteArray &	catalogName,
		const KLocalizedString &	programName,
		const QByteArray &	version,
		const KLocalizedString &	shortDescription = `KLocalizedString()`,
		enum LicenseKey	licenseType = `License_Unknown`,
		const KLocalizedString &	copyrightStatement = `KLocalizedString()`,
		const KLocalizedString &	text = `KLocalizedString()`,
		const QByteArray &	homePageAddress = `QByteArray()`,
		const QByteArray &	bugsEmailAddress = `"submit@bugs.kde.org"`
	)

Constructor.

Parameters:

	appName	The program name used internally. Example: "kedit"
	catalogName	The translation catalog name; if null or empty, the `appName` will be used. You may want the catalog name to differ from program name, for example, when you want to group translations of several smaller utilities under the same catalog.
	programName	A displayable program name string. This string should be marked for translation. Example: ki18n("KEdit")
	version	The program version string.
	shortDescription	A short description of what the program does. This string should be marked for translation. Example: ki18n("A simple text editor.")
	licenseType	The license identifier. Use setLicenseText if you use a license not predefined here.
	copyrightStatement	A copyright statement, that can look like this: ki18n("(c) 1999-2000, Name"). The string specified here is taken verbatim; the author information from addAuthor is not used.
	text	Some free form text, that can contain any kind of information. The text can contain newlines. This string should be marked for translation.
	homePageAddress	The program homepage string. Start the address with "http://". "http://some.domain" is is correct, "some.domain" is not. IMPORTANT: if you set a home page address, this will change the "organization domain" of the application, which is used for automatic DBUS registration.

See also:: setOrganizationDomain

Parameters:

bugsEmailAddress

The bug report email address string. This defaults to the kde.org bug system.

Definition at line 164 of file kaboutdata.cpp.

KAboutData::KAboutData ( const KAboutData & other )

Copy constructor.

Performs a deep copy.

Parameters:

other

object to copy

Definition at line 217 of file kaboutdata.cpp.

KAboutData::~KAboutData ( )

Definition at line 212 of file kaboutdata.cpp.

Member Function Documentation

KAboutData & KAboutData::operator= ( const KAboutData & other )

Assignment operator.

Performs a deep copy.

Parameters:

other

object to copy

Definition at line 223 of file kaboutdata.cpp.

KAboutData & KAboutData::addAuthor	(	const KLocalizedString &	name,
		const KLocalizedString &	task = `KLocalizedString()`,
		const QByteArray &	emailAddress = `QByteArray()`,
		const QByteArray &	webAddress = `QByteArray()`
	)

Defines an author.

You can call this function as many times as you need. Each entry is appended to a list. The person in the first entry is assumed to be the leader of the project.

Parameters:

	name	The developer's name. It should be marked for translation like this: ki18n("Developer Name")
	task	What the person is responsible for. This text can contain newlines. It should be marked for translation like this: ki18n("Task description..."). Can be left empty.
	emailAddress	An Email address where the person can be reached. Can be left empty.
	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 left empty.

Definition at line 230 of file kaboutdata.cpp.

KAboutData & KAboutData::addCredit	(	const KLocalizedString &	name,
		const KLocalizedString &	task = `KLocalizedString()`,
		const QByteArray &	emailAddress = `QByteArray()`,
		const QByteArray &	webAddress = `QByteArray()`
	)

Defines a person that deserves credit.

You can call this function as many times as you need. Each entry is appended to a list.

Parameters:

	name	The person's name. It should be marked for translation like this: ki18n("Contributor Name")
	task	What the person has done to deserve the honor. The text can contain newlines. It should be marked for translation like this: ki18n("Task description...") Can be left empty.
	emailAddress	An email address when the person can be reached. Can be left empty.
	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 left empty.

Definition at line 240 of file kaboutdata.cpp.

KAboutData & KAboutData::setTranslator	(	const KLocalizedString &	name,
		const KLocalizedString &	emailAddress
	)

Sets the name(s) of the translator(s) of the GUI.

Since this depends on the language, just use a dummy text marked for translation.

The canonical use is:

 setTranslator(ki18nc("NAME OF TRANSLATORS", "Your names"),
               ki18nc("EMAIL OF TRANSLATORS", "Your emails"));

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.

Parameters:

	name	the name(s) of the translator(s)
	emailAddress	the email address(es) of the translator(s)

See also:: KAboutTranslator

Definition at line 250 of file kaboutdata.cpp.

KAboutData & KAboutData::setLicenseText ( const KLocalizedString & license )

Defines a license text, which is marked for translation.

Example:

 setLicenseText( ki18n("This is my license") );

Parameters:

license

The license text.

Definition at line 259 of file kaboutdata.cpp.

KAboutData & KAboutData::setLicenseTextFile ( const QString & file )

Defines a license text by pointing to a file where it resides.

Parameters:

file

File containing the license text.

Definition at line 267 of file kaboutdata.cpp.

KAboutData & KAboutData::setAppName ( const QByteArray & appName )

Defines the program name used internally.

Parameters:

appName

The application name. Example: "kate".

Definition at line 275 of file kaboutdata.cpp.

KAboutData & KAboutData::setProgramName ( const KLocalizedString & programName )

Defines the displayable program name string.

Parameters:

programName

The program name. This string should be marked for translation. Example: ki18n("Advanced Text Editor").

Definition at line 282 of file kaboutdata.cpp.

KAboutData & KAboutData::setProgramLogo ( const QVariant & image )

Defines the program logo.

Use this if you need to have an application logo in AboutData other than the application icon.

Because KAboutData is in kdecore it cannot use QImage directly, so this is a QVariant that should contain a QImage.

Parameters:

image

logo image.

See also:: programLogo()

Definition at line 409 of file kaboutdata.cpp.

KAboutData & KAboutData::setVersion ( const QByteArray & version )

Defines the program version string.

Parameters:

version

The program version.

Definition at line 290 of file kaboutdata.cpp.

KAboutData & KAboutData::setShortDescription ( const KLocalizedString & shortDescription )

Defines a short description of what the program does.

Parameters:

shortDescription

The program description. This string should be marked for translation. Example: ki18n("An advanced text editor with syntax highlighting support.").

Definition at line 297 of file kaboutdata.cpp.

KAboutData & KAboutData::setCatalogName ( const QByteArray & catalogName )

Defines the translation catalog that the program uses.

Parameters:

catalogName

The translation catalog name.

Definition at line 304 of file kaboutdata.cpp.

KAboutData & KAboutData::setLicense ( LicenseKey licenseKey )

Defines the license identifier.

Parameters:

licenseKey

The license identifier.

Definition at line 311 of file kaboutdata.cpp.

KAboutData & KAboutData::setCopyrightStatement ( const KLocalizedString & copyrightStatement )

Defines the copyright statement to show when displaying the license.

Parameters:

copyrightStatement

Definition at line 318 of file kaboutdata.cpp.

KAboutData & KAboutData::setOtherText ( const KLocalizedString & otherText )

Defines the additional text to show in the about dialog.

Parameters:

otherText

Some free form text, that can contain any kind of information. The text can contain newlines. This string should be marked for translation.

Definition at line 325 of file kaboutdata.cpp.

KAboutData & KAboutData::setHomepage ( const QByteArray & homepage )

Defines the program homepage.

Parameters:

homepage

The program homepage string. Start the address with "http://". "http://kate.kde.org" is correct but "kate.kde.org" is not.

Definition at line 332 of file kaboutdata.cpp.

KAboutData & KAboutData::setBugAddress ( const QByteArray & bugAddress )

Defines the address where bug reports should be sent.

Parameters:

bugAddress

The bug report email address string. This defaults to the kde.org bug system.

Definition at line 339 of file kaboutdata.cpp.

KAboutData & KAboutData::setOrganizationDomain ( const QByteArray & domain )

Defines the Internet domain of the organization that wrote this application.

The domain is set to kde.org by default, or the domain of the homePageAddress constructor argument, if set.

Make sure to call setOrganizationDomain if your product is developed out of the kde.org version-control system.

Used by the automatic registration to DBus done by KApplication and KUniqueApplication.

IMPORTANT: if the organization domain is set, the .desktop file that describes your application should have an entry like X-DBUS-ServiceName=reversed_domain.kmyapp For instance kwrite passes "http://www.kate-editor.org" as the homePageAddress so it needs X-DBUS-ServiceName=org.kate-editor.kwrite in its kwrite.desktop file.

Parameters:

domain

the domain name, for instance kde.org, koffice.org, kdevelop.org, etc.

Definition at line 346 of file kaboutdata.cpp.

KAboutData & KAboutData::setProductName ( const QByteArray & name )

Defines the product name which 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. in the form 'product/component', such as 'kontact/summary'.

Parameters:

name

The name of product

Definition at line 353 of file kaboutdata.cpp.

QString KAboutData::appName ( ) const

Returns the application's internal name.

Returns:: the internal program name.

Definition at line 360 of file kaboutdata.cpp.

QString KAboutData::productName ( ) 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()

Returns:: the product name.

Definition at line 366 of file kaboutdata.cpp.

QString KAboutData::programName ( ) const

Returns the translated program name.

Returns:: the program name (translated).

Definition at line 374 of file kaboutdata.cpp.

QString KAboutData::organizationDomain ( ) const

Returns the domain name of the organization that wrote this application.

Used by the automatic registration to DBus done by KApplication and KUniqueApplication.

Definition at line 460 of file kaboutdata.cpp.

const char * KAboutData::internalProgramName ( ) const

Definition at line 385 of file kaboutdata.cpp.

void KAboutData::translateInternalProgramName ( ) const

Definition at line 395 of file kaboutdata.cpp.

QVariant KAboutData::programLogo ( ) const

Returns the program logo image.

Because KAboutData is in kdecore it cannot use QImage directly, so this is a QVariant containing a QImage.

Returns:: the program logo data, or a null image if there is no custom application logo defined.

Definition at line 403 of file kaboutdata.cpp.

QString KAboutData::version ( ) const

Returns the program's version.

Returns:: the version string.

Definition at line 416 of file kaboutdata.cpp.

const char * KAboutData::internalVersion ( ) const

Definition at line 425 of file kaboutdata.cpp.

QString KAboutData::shortDescription ( ) const

Returns a short, translated description.

Returns:: the short description (translated). Can be QString() if not set.

Definition at line 431 of file kaboutdata.cpp.

QString KAboutData::catalogName ( ) const

Returns the program's translation catalog name.

Returns:: the catalog name.

Definition at line 439 of file kaboutdata.cpp.

QString KAboutData::homepage ( ) const

Returns the application homepage.

Returns:: the application homepage URL. Can be QString() if not set.

Definition at line 448 of file kaboutdata.cpp.

QString KAboutData::bugAddress ( ) const

Returns the email address for bugs.

Returns:: the email address where to report bugs.

Definition at line 454 of file kaboutdata.cpp.

const char * KAboutData::internalBugAddress ( ) const

Definition at line 470 of file kaboutdata.cpp.

QList< KAboutPerson > KAboutData::authors ( ) const

Returns a list of authors.

Returns:: author information (list of persons).

Definition at line 478 of file kaboutdata.cpp.

QList< KAboutPerson > KAboutData::credits ( ) const

Returns a list of persons who contributed.

Returns:: credit information (list of persons).

Definition at line 484 of file kaboutdata.cpp.

QList< KAboutPerson > KAboutData::translators ( ) const

Returns a list of translators.

Returns:: translators information (list of persons)

Definition at line 492 of file kaboutdata.cpp.

QString KAboutData::aboutTranslationTeam ( ) [static]

Returns a message about the translation team.

Returns:: a message about the translation team

Definition at line 542 of file kaboutdata.cpp.

QString KAboutData::otherText ( ) const

Returns a translated, free form text.

Returns:: the free form text (translated). Can be QString() if not set.

Definition at line 553 of file kaboutdata.cpp.

QString KAboutData::license ( ) 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.

Returns:: The license text.

Definition at line 561 of file kaboutdata.cpp.

QString KAboutData::licenseName ( NameFormat formatName ) const

Returns the license name.

Returns:: The license name as a string.

Definition at line 623 of file kaboutdata.cpp.

QString KAboutData::copyrightStatement ( ) const

Returns the copyright statement.

Returns:: the copyright statement. Can be QString() if not set.

Definition at line 672 of file kaboutdata.cpp.

QString KAboutData::customAuthorPlainText ( ) const

Returns the plain text displayed around the list of authors instead of the default message telling users to send bug reports to bugAddress().

Returns:: the plain text displayed around the list of authors instead of the default message. Can be QString().

Definition at line 680 of file kaboutdata.cpp.

QString KAboutData::customAuthorRichText ( ) const

Returns the rich text displayed around the list of authors instead of the default message telling users to send bug reports to bugAddress().

Returns:: the rich text displayed around the list of authors instead of the default message. Can be QString().

Definition at line 688 of file kaboutdata.cpp.

bool KAboutData::customAuthorTextEnabled ( ) const

Returns whether custom text should be displayed around the list of authors.

Returns:: whether custom text should be displayed around the list of authors.

Definition at line 696 of file kaboutdata.cpp.

KAboutData & KAboutData::setCustomAuthorText	(	const KLocalizedString &	plainText,
		const KLocalizedString &	richText
	)

Sets the custom text displayed around the list of authors instead of the default message telling users to send bug reports to bugAddress().

Parameters:

	plainText	The plain text.
	richText	The rich text.

Setting both to parameters to KLocalizedString() will cause no message to be displayed at all. Call unsetCustomAuthorText() to revert to the default message.

Definition at line 702 of file kaboutdata.cpp.

KAboutData & KAboutData::unsetCustomAuthorText ( )

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().

Definition at line 714 of file kaboutdata.cpp.

The documentation for this class was generated from the following files:

KDECore

KAboutData Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

KDECore

kdelibs