KAboutData Class Reference

from PyKDE4.kdecore import *

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). They are also used for the icon and the name of the program's windows.

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

Enumerations
LicenseKey	{ 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, License_GPL_V3, License_LGPL_V3 }
NameFormat	{ ShortName, FullName }
Methods
	__init__ (self, QByteArray appName, QByteArray catalogName, KLocalizedString programName, QByteArray version, KLocalizedString shortDescription=KLocalizedString(), KAboutData.LicenseKey licenseType=KAboutData.License_Unknown, KLocalizedString copyrightStatement=KLocalizedString(), KLocalizedString text=KLocalizedString(), QByteArray homePageAddress=QByteArray(), QByteArray bugsEmailAddress="submit@bugs.kde.org")
	__init__ (self, KAboutData other)
KAboutData	addAuthor (self, KLocalizedString name, KLocalizedString task=KLocalizedString(), QByteArray emailAddress=QByteArray(), QByteArray webAddress=QByteArray())
KAboutData	addCredit (self, KLocalizedString name, KLocalizedString task=KLocalizedString(), QByteArray emailAddress=QByteArray(), QByteArray webAddress=QByteArray())
KAboutData	addLicense (self, KAboutData.LicenseKey licenseKey)
KAboutData	addLicenseText (self, KLocalizedString license)
KAboutData	addLicenseTextFile (self, QString file)
QString	appName (self)
[KAboutPerson]	authors (self)
QString	bugAddress (self)
QString	catalogName (self)
QString	copyrightStatement (self)
[KAboutPerson]	credits (self)
QString	customAuthorPlainText (self)
QString	customAuthorRichText (self)
bool	customAuthorTextEnabled (self)
QString	homepage (self)
QString	internalBugAddress (self)
QString	internalProgramName (self)
QString	internalVersion (self)
QString	license (self)
QString	licenseName (self, KAboutData.NameFormat formatName)
[KAboutLicense]	licenses (self)
QString	organizationDomain (self)
QString	otherText (self)
QString	productName (self)
QString	programIconName (self)
QVariant	programLogo (self)
QString	programName (self)
KAboutData	setAppName (self, QByteArray appName)
KAboutData	setBugAddress (self, QByteArray bugAddress)
KAboutData	setCatalogName (self, QByteArray catalogName)
KAboutData	setCopyrightStatement (self, KLocalizedString copyrightStatement)
KAboutData	setCustomAuthorText (self, KLocalizedString plainText, KLocalizedString richText)
KAboutData	setHomepage (self, QByteArray homepage)
KAboutData	setLicense (self, KAboutData.LicenseKey licenseKey)
KAboutData	setLicenseText (self, KLocalizedString license)
KAboutData	setLicenseTextFile (self, QString file)
KAboutData	setOrganizationDomain (self, QByteArray domain)
KAboutData	setOtherText (self, KLocalizedString otherText)
KAboutData	setProductName (self, QByteArray name)
KAboutData	setProgramIconName (self, QString iconName)
KAboutData	setProgramLogo (self, QVariant image)
KAboutData	setProgramName (self, KLocalizedString programName)
KAboutData	setShortDescription (self, KLocalizedString shortDescription)
KAboutData	setTranslator (self, KLocalizedString name, KLocalizedString emailAddress)
KAboutData	setVersion (self, QByteArray version)
QString	shortDescription (self)
	translateInternalProgramName (self)
[KAboutPerson]	translators (self)
KAboutData	unsetCustomAuthorText (self)
QString	version (self)
Static Methods
QString	aboutTranslationTeam ()

Method Documentation

__init__	(	self,
		QByteArray	appName,
		QByteArray	catalogName,
		KLocalizedString	programName,
		QByteArray	version,
		KLocalizedString	shortDescription=KLocalizedString(),
		KAboutData.LicenseKey	licenseType=KAboutData.License_Unknown,
		KLocalizedString	copyrightStatement=KLocalizedString(),
		KLocalizedString	text=KLocalizedString(),
		QByteArray	homePageAddress=QByteArray(),
		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 or setLicenseTextFile 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.

__init__	(	self,
		KAboutData	other
	)

Copy constructor. Performs a deep copy.

Parameters:

other

object to copy

QString aboutTranslationTeam ( )

Returns a message about the translation team.

Returns:: a message about the translation team

KAboutData addAuthor	(	self,
		KLocalizedString	name,
		KLocalizedString	task=KLocalizedString(),
		QByteArray	emailAddress=QByteArray(),
		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.

KAboutData addCredit	(	self,
		KLocalizedString	name,
		KLocalizedString	task=KLocalizedString(),
		QByteArray	emailAddress=QByteArray(),
		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.

KAboutData addLicense	(	self,
		KAboutData.LicenseKey	licenseKey
	)

Adds a license identifier.

If there is only one unknown license set, e.g. by using the default parameter in the constructor, that one is replaced.

Parameters:

licenseKey

The license identifier.

See also:: setLicenseText, addLicenseText, addLicenseTextFile

Since:: 4.1

KAboutData addLicenseText	(	self,
		KLocalizedString	license
	)

Adds a license text, which is marked for translation.

If there is only one unknown license set, e.g. by using the default parameter in the constructor, that one is replaced.

Example:

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

Parameters:

license

The license text.

See also:: setLicenseText, addLicense, addLicenseTextFile

Since:: 4.1

KAboutData addLicenseTextFile	(	self,
		QString	file
	)

Adds a license text by pointing to a file where it resides. The file format has to be plain text in an encoding compatible to the locale.

If there is only one unknown license set, e.g. by using the default parameter in the constructor, that one is replaced.

Parameters:

file

Path to the file in the local filesystem containing the license text.

See also:: addLicenseText, addLicense, setLicenseTextFile

Since:: 4.1

QString appName ( self )

Returns the application's internal name.

Returns:: the internal program name.

[KAboutPerson] authors ( self )

Returns a list of authors.

Returns:: author information (list of persons).

QString bugAddress ( self )

Returns the email address for bugs.

Returns:: the email address where to report bugs.

QString catalogName ( self )

Returns the program's translation catalog name.

Returns:: the catalog name.

QString copyrightStatement ( self )

Returns the copyright statement.

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

[KAboutPerson] credits ( self )

Returns a list of persons who contributed.

Returns:: credit information (list of persons).

QString customAuthorPlainText ( self )

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

QString customAuthorRichText ( self )

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

bool customAuthorTextEnabled ( self )

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

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

QString homepage ( self )

Returns the application homepage.

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

QString internalBugAddress ( self )

Internal:: Provided for use by KCrash

QString internalProgramName ( self )

Internal:: Provided for use by KCrash

QString internalVersion ( self )

Internal:: Provided for use by KCrash

QString license ( self )

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.

Deprecated:: There could be multiple licenses, use licenses() instead.

QString licenseName	(	self,
		KAboutData.NameFormat	formatName
	)

Returns the license name.

Returns:: The license name as a string.

Deprecated:: There could be multiple licenses, use licenses() instead.

[KAboutLicense] licenses ( self )

Returns a list of licenses.

Returns:: licenses information (list of licenses)

Since:: 4.1

QString organizationDomain ( self )

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

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

QString otherText ( self )

Returns a translated, free form text.

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

QString productName ( self )

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.

QString programIconName ( self )

Returns the program's icon name.

The default value is appName . Use setProgramIconName if you need to have an icon whose name is different from the internal application name.

Returns:: the program's icon name.

See also:: setProgramIconName()

Since:: 4.1

QVariant programLogo ( self )

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.

QString programName ( self )

Returns the translated program name.

Returns:: the program name (translated).

KAboutData setAppName	(	self,
		QByteArray	appName
	)

Defines the program name used internally.

Parameters:

appName

The application name. Example: "kate".

KAboutData setBugAddress	(	self,
		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.

KAboutData setCatalogName	(	self,
		QByteArray	catalogName
	)

Defines the translation catalog that the program uses.

Parameters:

catalogName

The translation catalog name.

KAboutData setCopyrightStatement	(	self,
		KLocalizedString	copyrightStatement
	)

Defines the copyright statement to show when displaying the license.

Parameters:

copyrightStatement

KAboutData setCustomAuthorText	(	self,
		KLocalizedString	plainText,
		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.

KAboutData setHomepage	(	self,
		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.

KAboutData setLicense	(	self,
		KAboutData.LicenseKey	licenseKey
	)

Defines the license identifier.

Parameters:

licenseKey

The license identifier.

See also:: addLicenseText, setLicenseText, setLicenseTextFile

KAboutData setLicenseText	(	self,
		KLocalizedString	license
	)

Defines a license text, which is marked for translation.

Example:

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

Parameters:

license

The license text.

KAboutData setLicenseTextFile	(	self,
		QString	file
	)

Defines a license text by pointing to a file where it resides. The file format has to be plain text in an encoding compatible to the locale.

Parameters:

file

Path to the file in the local filesystem containing the license text.

KAboutData setOrganizationDomain	(	self,
		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.

KAboutData setOtherText	(	self,
		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.

KAboutData setProductName	(	self,
		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

KAboutData setProgramIconName	(	self,
		QString	iconName
	)

Defines the program icon.

Use this if you need to have an application icon whose name is different than the application name.

Parameters:

iconName

name of the icon. Example: "accessories-text-editor"

See also:: programIconName()

Since:: 4.1

KAboutData setProgramLogo	(	self,
		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()

KAboutData setProgramName	(	self,
		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").

KAboutData setShortDescription	(	self,
		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.").

KAboutData setTranslator	(	self,
		KLocalizedString	name,
		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

KAboutData setVersion	(	self,
		QByteArray	version
	)

Defines the program version string.

Parameters:

version

The program version.

QString shortDescription ( self )

Returns a short, translated description.

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

translateInternalProgramName ( self )

Internal:: Provided for use by KCrash

[KAboutPerson] translators ( self )

Returns a list of translators.

Returns:: translators information (list of persons)

KAboutData unsetCustomAuthorText ( self )

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

QString version ( self )

Returns the program's version.

Returns:: the version string.

Enumeration Documentation

LicenseKey

Describes the license of the software.

Enumerator:

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
License_GPL_V3 = 6
License_LGPL_V3 = 7

NameFormat

Format of the license name.

Enumerator:

ShortName
FullName

KAboutData Class Reference

Detailed Description

Enumerations

Methods

Static Methods

Method Documentation

Enumeration Documentation

Modules