KDECore
KAboutData Class Reference
This class is used to store information about a program. More...
#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). 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.
Definition at line 165 of file kaboutdata.h.
Member Enumeration Documentation
Describes 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 License_GPL_V3 License_LGPL_V3
Definition at line 171 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 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.
Definition at line 416 of file kaboutdata.cpp.
KAboutData::KAboutData | ( | const KAboutData & | other | ) |
Copy constructor.
Performs a deep copy.
- Parameters:
-
other object to copy
Definition at line 469 of file kaboutdata.cpp.
KAboutData::~KAboutData | ( | ) |
Definition at line 464 of file kaboutdata.cpp.
Member Function Documentation
QString KAboutData::aboutTranslationTeam | ( | ) | [static] |
Returns a message about the translation team.
- Returns:
- a message about the translation team
Definition at line 844 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 482 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 492 of file kaboutdata.cpp.
KAboutData & KAboutData::addLicense | ( | 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
Definition at line 594 of file kaboutdata.cpp.
KAboutData & KAboutData::addLicenseText | ( | const 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
Definition at line 518 of file kaboutdata.cpp.
KAboutData & KAboutData::addLicenseTextFile | ( | const 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
Definition at line 538 of file kaboutdata.cpp.
QString KAboutData::appName | ( | ) | const |
Returns the application's internal name.
- Returns:
- the internal program name.
Definition at line 649 of file kaboutdata.cpp.
QList< KAboutPerson > KAboutData::authors | ( | ) | const |
Returns a list of authors.
- Returns:
- author information (list of persons).
Definition at line 780 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 756 of file kaboutdata.cpp.
QString KAboutData::catalogName | ( | ) | const |
Returns the program's translation catalog name.
- Returns:
- the catalog name.
Definition at line 741 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 881 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 786 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 889 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 897 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 905 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 750 of file kaboutdata.cpp.
const char * KAboutData::internalBugAddress | ( | ) | const |
For internal use only.
Provided for use by KCrash
Return the untranslated and uninterpreted (to UTF8) string for the bug mail address. Used in particular for KCrash.
Definition at line 772 of file kaboutdata.cpp.
const char * KAboutData::internalProgramName | ( | ) | const |
For internal use only.
Provided for use by KCrash
Return the program name. It is always pre-allocated. Needed for KCrash in particular.
Definition at line 674 of file kaboutdata.cpp.
const char * KAboutData::internalVersion | ( | ) | const |
For internal use only.
Provided for use by KCrash
Return the untranslated and uninterpreted (to UTF8) string for the version information. Used in particular for KCrash.
Definition at line 727 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.
- Deprecated:
- There could be multiple licenses, use licenses() instead.
Definition at line 863 of file kaboutdata.cpp.
QString KAboutData::licenseName | ( | NameFormat | formatName | ) | const |
Returns the license name.
- Returns:
- The license name as a string.
- Deprecated:
- There could be multiple licenses, use licenses() instead.
Definition at line 869 of file kaboutdata.cpp.
QList< KAboutLicense > KAboutData::licenses | ( | ) | const |
Returns a list of licenses.
- Returns:
- licenses information (list of licenses)
- Since:
- 4.1
Definition at line 875 of file kaboutdata.cpp.
KAboutData & KAboutData::operator= | ( | const KAboutData & | other | ) |
Assignment operator.
Performs a deep copy.
- Parameters:
-
other object to copy
Definition at line 475 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 762 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 855 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 655 of file kaboutdata.cpp.
QString KAboutData::programIconName | ( | ) | const |
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
Definition at line 692 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 705 of file kaboutdata.cpp.
QString KAboutData::programName | ( | ) | const |
Returns the translated program name.
- Returns:
- the program name (translated).
Definition at line 663 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 551 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 628 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 580 of file kaboutdata.cpp.
KAboutData & KAboutData::setCopyrightStatement | ( | const KLocalizedString & | copyrightStatement | ) |
Defines the copyright statement to show when displaying the license.
- Parameters:
-
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.
Definition at line 607 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.
Definition at line 911 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 621 of file kaboutdata.cpp.
KAboutData & KAboutData::setLicense | ( | LicenseKey | licenseKey | ) |
Defines the license identifier.
- Parameters:
-
licenseKey The license identifier.
- See also:
- addLicenseText, setLicenseText, setLicenseTextFile
Definition at line 587 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 511 of file kaboutdata.cpp.
KAboutData & KAboutData::setLicenseTextFile | ( | const 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.
Definition at line 531 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 635 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 614 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 642 of file kaboutdata.cpp.
KAboutData & KAboutData::setProgramIconName | ( | const 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
Definition at line 698 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 711 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 558 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 573 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 502 of file kaboutdata.cpp.
KAboutData & KAboutData::setVersion | ( | const QByteArray & | version | ) |
Defines the program version string.
- Parameters:
-
version The program version.
Definition at line 566 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 733 of file kaboutdata.cpp.
void KAboutData::translateInternalProgramName | ( | ) | const |
For internal use only.
Provided for use by KCrash
KCrash should call as few things as possible and should avoid e.g. malloc() because it may deadlock. Since i18n() needs it, when KLocale is available the i18n() call will be done here in advance.
Definition at line 684 of file kaboutdata.cpp.
QList< KAboutPerson > KAboutData::translators | ( | ) | const |
Returns a list of translators.
- Returns:
- translators information (list of persons)
Definition at line 794 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 923 of file kaboutdata.cpp.
QString KAboutData::version | ( | ) | const |
Returns the program's version.
- Returns:
- the version string.
Definition at line 718 of file kaboutdata.cpp.
The documentation for this class was generated from the following files: