1/*
2 * This file is part of the KDE Libraries
3 * Copyright (C) 2000 Espen Sand (espen@kde.org)
4 * Copyright (C) 2008 Friedrich W. H. Kossebau <kossebau@kde.org>
5 * Copyright (C) 2010 Teo Mrnjavac <teo@kde.org>
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public License
18 * along with this library; see the file COPYING.LIB. If not, write to
19 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 *
22 */
23
24#ifndef KABOUTDATA_H
25#define KABOUTDATA_H
26
27#include <kdecore_export.h>
28#include <klocale.h>
29// Qt
30#include <QtCore/QString>
31#include <QtCore/QSharedDataPointer>
32
33template <class T> class QList;
34class QVariant;
35class KAboutData;
36
37/**
38 * This class is used to store information about a person or developer.
39 * It can store the person's name, a task, an email address and a
40 * link to a home page. This class is intended for use in the
41 * KAboutData class, but it can be used elsewhere as well.
42 * Normally you should at least define the person's name.
43 * Creating a KAboutPerson object by yourself is relatively useless,
44 * but the KAboutData methods KAboutData::authors() and KAboutData::credits()
45 * return lists of KAboutPerson data objects which you can examine.
46 *
47 * Example usage within a main(), retrieving the list of people involved
48 * with a program and re-using data from one of them:
49 *
50 * @code
51 * KAboutData about("khello", "khello", ki18n("KHello"), "0.1",
52 * ki18n("A KDE version of Hello, world!"),
53 * KAboutData::License_LGPL,
54 * ki18n("Copyright (C) 2003 Developer"));
55 *
56 * about.addAuthor(ki18n("Joe Developer"), ki18n("developer"), "joe@host.com", 0);
57 * QList<KAboutPerson> people = about.authors();
58 * about.addCredit(people[0].name(), people[0].task());
59 * @endcode
60 *
61 * @note Instead of the more usual i18n calls, for translatable text the ki18n
62 * calls are used to produce KLocalizedStrings, which can delay the translation
63 * lookup. This is necessary because the translation catalogs are usually not
64 * yet initialized at the point where KAboutData is constructed.
65 *
66 * @bc KDE4
67 */
68class KDECORE_EXPORT KAboutPerson
69{
70 friend class KAboutData;
71public:
72 /**
73 * Convenience constructor
74 *
75 * @param name The name of the person.
76 *
77 * @param task The task of this person.
78 *
79 * @param emailAddress The email address of the person.
80 *
81 * @param webAddress Home page of the person.
82 */
83 explicit KAboutPerson( const KLocalizedString &name,
84 const KLocalizedString &task = KLocalizedString(),
85 const QByteArray &emailAddress = QByteArray(),
86 const QByteArray &webAddress = QByteArray() );
87
88 /**
89 * Convenience constructor with Open Collaboration Services data
90 *
91 * @param name The name of the person.
92 *
93 * @param task The task of this person.
94 *
95 * @param emailAddress The email address of the person.
96 *
97 * @param webAddress Home page of the person.
98 *
99 * @param ocsUsername Open Collaboration Services username of the person.
100 */
101 explicit KAboutPerson( const KLocalizedString &name,
102 const KLocalizedString &task,
103 const QByteArray &emailAddress,
104 const QByteArray &webAddress,
105 const QByteArray &ocsUsername ); //KDE5: merge into main ctor
106
107 /**
108 * Copy constructor. Performs a deep copy.
109 * @param other object to copy
110 */
111 KAboutPerson(const KAboutPerson& other);
112
113 ~KAboutPerson();
114
115 /**
116 * Assignment operator. Performs a deep copy.
117 * @param other object to copy
118 */
119 KAboutPerson& operator=(const KAboutPerson& other);
120
121
122 /**
123 * The person's name
124 * @return the person's name (can be QString(), if it has been
125 * constructed with an empty name)
126 */
127 QString name() const;
128
129 /**
130 * The person's task
131 * @return the person's task (can be QString(), if it has been
132 * constructed with an empty task)
133 */
134 QString task() const;
135
136 /**
137 * The person's email address
138 * @return the person's email address (can be QString(), if it has been
139 * constructed with an empty email)
140 */
141 QString emailAddress() const;
142
143 /**
144 * The home page or a relevant link
145 * @return the persons home page (can be QString(), if it has been
146 * constructed with an empty home page)
147 */
148 QString webAddress() const;
149
150 /**
151 * The person's Open Collaboration Services username
152 * @return the persons OCS username (can be QString(), if it has been
153 * constructed with an empty username)
154 */
155 QString ocsUsername() const;
156
157private:
158 /**
159 * @internal Used by KAboutData to construct translator data.
160 */
161 explicit KAboutPerson( const QString &name, const QString &email );
162
163 class Private;
164 Private *const d;
165};
166
167class KAboutLicense;
168
169// KDE5: refactor together with KComponentData.
170// Like changing all property names which contain Program or App.
171
172/**
173 * This class is used to store information about a program. It can store
174 * such values as version number, program name, home page, email address
175 * for bug reporting, multiple authors and contributors
176 * (using KAboutPerson), license and copyright information.
177 *
178 * Currently, the values set here are shown by the "About" box
179 * (see KAboutDialog), used by the bug report dialog (see KBugReport),
180 * and by the help shown on command line (see KCmdLineArgs).
181 * They are also used for the icon and the name of the program's windows.
182 *
183 * @note Instead of the more usual i18n calls, for translatable text the ki18n
184 * calls are used to produce KLocalizedStrings, which can delay the translation
185 * lookup. This is necessary because the translation catalogs are usually not
186 * yet initialized at the point where KAboutData is constructed.
187 *
188 * @short Holds information needed by the "About" box and other
189 * classes.
190 * @author Espen Sand (espen@kde.org), David Faure (faure@kde.org)
191 */
192class KDECORE_EXPORT KAboutData
193{
194 public:
195 /**
196 * Describes the license of the software.
197 */
198 enum LicenseKey // KDE5: move to KAboutLicense, cut License_ prefix
199 {
200 License_Custom = -2,
201 License_File = -1,
202 License_Unknown = 0,
203 License_GPL = 1,
204 License_GPL_V2 = 1,
205 License_LGPL = 2,
206 License_LGPL_V2 = 2,
207 License_BSD = 3,
208 License_Artistic = 4,
209 License_QPL = 5,
210 License_QPL_V1_0 = 5,
211 License_GPL_V3 = 6,
212 License_LGPL_V3 = 7
213 };
214
215 /**
216 * Format of the license name.
217 */
218 enum NameFormat // KDE5: move to KAboutLicense
219 {
220 ShortName,
221 FullName
222 };
223
224 public:
225 /**
226 * Constructor.
227 *
228 * @param appName The program name used internally. Example: "kedit"
229 *
230 * @param catalogName The translation catalog name; if null or empty, the
231 * @p appName will be used. You may want the catalog name to
232 * differ from program name, for example, when you want to group
233 * translations of several smaller utilities under the same catalog.
234 *
235 * @param programName A displayable program name string. This string
236 * should be marked for translation. Example: ki18n("KEdit")
237 *
238 * @param version The program version string.
239 *
240 * @param shortDescription A short description of what the program does.
241 * This string should be marked for translation.
242 * Example: ki18n("A simple text editor.")
243 *
244 * @param licenseType The license identifier. Use setLicenseText or
245 setLicenseTextFile if you use a license not predefined here.
246 *
247 * @param copyrightStatement A copyright statement, that can look like this:
248 * ki18n("Copyright (C) 1999-2000 Name"). The string specified here is
249 * taken verbatim; the author information from addAuthor is not used.
250 *
251 * @param otherText Some free form text, that can contain any kind of
252 * information. The text can contain newlines. This string
253 * should be marked for translation.
254 *
255 * @param homePageAddress The program homepage string.
256 * Start the address with "http://". "http://some.domain" is
257 * is correct, "some.domain" is not.
258 * IMPORTANT: if you set a home page address, this will change the "organization domain"
259 * of the application, which is used for automatic D-Bus registration.
260 * @see setOrganizationDomain
261 *
262 * @param bugsEmailAddress The bug report email address string.
263 * This defaults to the kde.org bug system.
264 *
265 */
266 KAboutData( const QByteArray &appName,
267 const QByteArray &catalogName,
268 const KLocalizedString &programName,
269 const QByteArray &version,
270 const KLocalizedString &shortDescription = KLocalizedString(),
271 enum LicenseKey licenseType = License_Unknown,
272 const KLocalizedString &copyrightStatement = KLocalizedString(),
273 const KLocalizedString &otherText = KLocalizedString(),
274 const QByteArray &homePageAddress = QByteArray(),
275 const QByteArray &bugsEmailAddress = "submit@bugs.kde.org"
276 );
277
278 /**
279 * Copy constructor. Performs a deep copy.
280 * @param other object to copy
281 */
282 KAboutData(const KAboutData& other);
283
284 /**
285 * Assignment operator. Performs a deep copy.
286 * @param other object to copy
287 */
288 KAboutData& operator=(const KAboutData& other);
289
290 ~KAboutData();
291
292 /**
293 * Defines an author.
294 *
295 * You can call this function as many times as you need. Each entry is
296 * appended to a list. The person in the first entry is assumed to be
297 * the leader of the project.
298 *
299 * @param name The developer's name. It should be marked for translation
300 * like this: ki18n("Developer Name")
301 *
302 * @param task What the person is responsible for. This text can contain
303 * newlines. It should be marked for translation like this:
304 * ki18n("Task description..."). Can be left empty.
305 *
306 * @param emailAddress An Email address where the person can be reached.
307 * Can be left empty.
308 *
309 * @param webAddress The person's homepage or a relevant link.
310 * Start the address with "http://". "http://some.domain" is
311 * correct, "some.domain" is not. Can be left empty.
312 *
313 */
314 KAboutData &addAuthor( const KLocalizedString &name,
315 const KLocalizedString &task = KLocalizedString(),
316 const QByteArray &emailAddress = QByteArray(),
317 const QByteArray &webAddress = QByteArray() );
318
319 /**
320 * Defines an author.
321 *
322 * You can call this function as many times as you need. Each entry is
323 * appended to a list. The person in the first entry is assumed to be
324 * the leader of the project.
325 *
326 * @param name The developer's name. It should be marked for translation
327 * like this: ki18n("Developer Name")
328 *
329 * @param task What the person is responsible for. This text can contain
330 * newlines. It should be marked for translation like this:
331 * ki18n("Task description..."). Can be left empty.
332 *
333 * @param emailAddress An Email address where the person can be reached.
334 * Can be left empty.
335 *
336 * @param webAddress The person's homepage or a relevant link.
337 * Start the address with "http://". "http://some.domain" is
338 * correct, "some.domain" is not. Can be left empty.
339 *
340 * @param ocsUsername The person's Open Collaboration Services username.
341 * The provider can be optionally specified with @see setOcsProvider.
342 *
343 */
344 KAboutData &addAuthor( const KLocalizedString &name,
345 const KLocalizedString &task,
346 const QByteArray &emailAddress,
347 const QByteArray &webAddress,
348 const QByteArray &ocsUsername ); //KDE5: merge with addAuthor
349
350 /**
351 * Defines a person that deserves credit.
352 *
353 * You can call this function as many times as you need. Each entry
354 * is appended to a list.
355 *
356 * @param name The person's name. It should be marked for translation
357 * like this: ki18n("Contributor Name")
358 *
359 * @param task What the person has done to deserve the honor. The
360 * text can contain newlines. It should be marked for
361 * translation like this: ki18n("Task description...")
362 * Can be left empty.
363 *
364 * @param emailAddress An email address when the person can be reached.
365 * Can be left empty.
366 *
367 * @param webAddress The person's homepage or a relevant link.
368 * Start the address with "http://". "http://some.domain" is
369 * is correct, "some.domain" is not. Can be left empty.
370 *
371 */
372 KAboutData &addCredit( const KLocalizedString &name,
373 const KLocalizedString &task = KLocalizedString(),
374 const QByteArray &emailAddress = QByteArray(),
375 const QByteArray &webAddress = QByteArray() );
376
377 /**
378 * Defines a person that deserves credit.
379 *
380 * You can call this function as many times as you need. Each entry
381 * is appended to a list.
382 *
383 * @param name The person's name. It should be marked for translation
384 * like this: ki18n("Contributor Name")
385 *
386 * @param task What the person has done to deserve the honor. The
387 * text can contain newlines. It should be marked for
388 * translation like this: ki18n("Task description...")
389 * Can be left empty.
390 *
391 * @param emailAddress An email address when the person can be reached.
392 * Can be left empty.
393 *
394 * @param webAddress The person's homepage or a relevant link.
395 * Start the address with "http://". "http://some.domain" is
396 * is correct, "some.domain" is not. Can be left empty.
397 *
398 * @param ocsUsername The person's Open Collaboration Services username.
399 * The provider can be optionally specified with @see setOcsProvider.
400 *
401 */
402 KAboutData &addCredit( const KLocalizedString &name,
403 const KLocalizedString &task,
404 const QByteArray &emailAddress,
405 const QByteArray &webAddress,
406 const QByteArray &ocsUsername ); //KDE5: merge with addCredit
407
408 /**
409 * @brief Sets the name(s) of the translator(s) of the GUI.
410 *
411 * Since this depends on the language, just use a dummy text marked for
412 * translation.
413 *
414 * The canonical use is:
415 *
416 * \code
417 * setTranslator(ki18nc("NAME OF TRANSLATORS", "Your names"),
418 * ki18nc("EMAIL OF TRANSLATORS", "Your emails"));
419 * \endcode
420 *
421 * The translator can then translate this dummy text with his name
422 * or with a list of names separated with ",".
423 * If there is no translation or the application is used with the
424 * default language, this function call is ignored.
425 *
426 * @param name the name(s) of the translator(s)
427 * @param emailAddress the email address(es) of the translator(s)
428 * @see KAboutTranslator
429 */
430 KAboutData &setTranslator( const KLocalizedString& name,
431 const KLocalizedString& emailAddress );
432
433 /**
434 * Defines a license text, which is marked for translation.
435 *
436 * Example:
437 * \code
438 * setLicenseText( ki18n("This is my license") );
439 * \endcode
440 *
441 * @param license The license text.
442 */
443 KAboutData &setLicenseText( const KLocalizedString &license );
444
445 /**
446 * Adds a license text, which is marked for translation.
447 *
448 * If there is only one unknown license set, e.g. by using the default
449 * parameter in the constructor, that one is replaced.
450 *
451 * Example:
452 * \code
453 * addLicenseText( ki18n("This is my license") );
454 * \endcode
455 *
456 * @param license The license text.
457 * @see setLicenseText, addLicense, addLicenseTextFile
458 * @since 4.1
459 */
460 KAboutData &addLicenseText( const KLocalizedString &license );
461
462 /**
463 * Defines a license text by pointing to a file where it resides.
464 * The file format has to be plain text in an encoding compatible to the locale.
465 *
466 * @param file Path to the file in the local filesystem containing the license text.
467 */
468 KAboutData &setLicenseTextFile( const QString &file );
469
470 /**
471 * Adds a license text by pointing to a file where it resides.
472 * The file format has to be plain text in an encoding compatible to the locale.
473 *
474 * If there is only one unknown license set, e.g. by using the default
475 * parameter in the constructor, that one is replaced.
476 *
477 * @param file Path to the file in the local filesystem containing the license text.
478 * @see addLicenseText, addLicense, setLicenseTextFile
479 * @since 4.1
480 */
481 KAboutData &addLicenseTextFile( const QString &file );
482
483 /**
484 * Defines the program name used internally.
485 *
486 * @param appName The application name. Example: "kate".
487 */
488 KAboutData &setAppName( const QByteArray &appName );
489
490 /**
491 * Defines the displayable program name string.
492 *
493 * @param programName The program name. This string should be
494 * marked for translation.
495 * Example: ki18n("Advanced Text Editor").
496 */
497 KAboutData &setProgramName( const KLocalizedString &programName );
498
499 /**
500 * Defines the program icon.
501 *
502 * Use this if you need to have an application icon
503 * whose name is different than the application name.
504 *
505 * @param iconName name of the icon. Example: "accessories-text-editor"
506 * @see programIconName()
507 * @since 4.1
508 */
509 KAboutData &setProgramIconName( const QString &iconName );
510
511 /**
512 * Defines the program logo.
513 *
514 * Use this if you need to have an application logo
515 * in AboutData other than the application icon.
516 *
517 * Because KAboutData is in kdecore it cannot use QImage directly,
518 * so this is a QVariant that should contain a QImage.
519 *
520 * @param image logo image.
521 * @see programLogo()
522 */
523 KAboutData &setProgramLogo(const QVariant& image);
524
525 /**
526 * Specifies an Open Collaboration Services provider by URL.
527 * A provider file must be available for the chosen provider.
528 *
529 * Use this if you need to override the default provider.
530 *
531 * If this method is not used, all the KAboutPerson OCS usernames
532 * will be used with the openDesktop.org entry from the default
533 * provider file.
534 *
535 * @param providerUrl The provider URL as defined in the provider file.
536 */
537 KAboutData &setOcsProvider( const QByteArray &providerUrl );
538
539 /**
540 * Defines the program version string.
541 *
542 * @param version The program version.
543 */
544 KAboutData &setVersion( const QByteArray &version );
545
546 /**
547 * Defines a short description of what the program does.
548 *
549 * @param shortDescription The program description. This string should
550 * be marked for translation. Example: ki18n("An advanced text
551 * editor with syntax highlighting support.").
552 */
553 KAboutData &setShortDescription( const KLocalizedString &shortDescription );
554
555 /**
556 * Defines the translation catalog that the program uses.
557 *
558 * @param catalogName The translation catalog name.
559 */
560 KAboutData &setCatalogName( const QByteArray &catalogName );
561
562 /**
563 * Defines the license identifier.
564 *
565 * @param licenseKey The license identifier.
566 * @see addLicenseText, setLicenseText, setLicenseTextFile
567 */
568 KAboutData &setLicense( LicenseKey licenseKey );
569
570 /**
571 * Adds a license identifier.
572 *
573 * If there is only one unknown license set, e.g. by using the default
574 * parameter in the constructor, that one is replaced.
575 *
576 * @param licenseKey The license identifier.
577 * @see setLicenseText, addLicenseText, addLicenseTextFile
578 * @since 4.1
579 */
580 KAboutData &addLicense( LicenseKey licenseKey );
581
582 /**
583 * Defines the copyright statement to show when displaying the license.
584 *
585 * @param copyrightStatement A copyright statement, that can look like
586 * this: ki18n("Copyright (C) 1999-2000 Name"). The string specified here is
587 * taken verbatim; the author information from addAuthor is not used.
588 */
589 KAboutData &setCopyrightStatement( const KLocalizedString &copyrightStatement );
590
591 /**
592 * Defines the additional text to show in the about dialog.
593 *
594 * @param otherText Some free form text, that can contain any kind of
595 * information. The text can contain newlines. This string
596 * should be marked for translation.
597 */
598 KAboutData &setOtherText( const KLocalizedString &otherText );
599
600 /**
601 * Defines the program homepage.
602 *
603 * @param homepage The program homepage string.
604 * Start the address with "http://". "http://kate.kde.org"
605 * is correct but "kate.kde.org" is not.
606 */
607 KAboutData &setHomepage( const QByteArray &homepage );
608
609 /**
610 * Defines the address where bug reports should be sent.
611 *
612 * @param bugAddress The bug report email address string.
613 * This defaults to the kde.org bug system.
614 */
615 KAboutData &setBugAddress( const QByteArray &bugAddress );
616
617 /**
618 * Defines the Internet domain of the organization that wrote this application.
619 * The domain is set to kde.org by default, or the domain of the homePageAddress constructor argument,
620 * if set.
621 *
622 * Make sure to call setOrganizationDomain if your product is developed out of the
623 * kde.org version-control system.
624 *
625 * Used by the automatic registration to D-Bus done by KApplication and KUniqueApplication.
626 *
627 * IMPORTANT: if the organization domain is set, the .desktop file that describes your
628 * application should have an entry like X-DBUS-ServiceName=reversed_domain.kmyapp
629 * For instance kwrite passes "http://www.kate-editor.org" as the homePageAddress so it needs
630 * X-DBUS-ServiceName=org.kate-editor.kwrite in its kwrite.desktop file.
631 *
632 * @param domain the domain name, for instance kde.org, koffice.org, kdevelop.org, etc.
633 */
634 KAboutData &setOrganizationDomain( const QByteArray &domain );
635
636 /**
637 * Defines the product name which will be used in the KBugReport dialog.
638 * By default it's the appName, but you can overwrite it here to provide
639 * support for special components e.g. in the form 'product/component',
640 * such as 'kontact/summary'.
641 *
642 * @param name The name of product
643 */
644 KAboutData &setProductName( const QByteArray &name );
645
646 /**
647 * Returns the application's internal name.
648 * @return the internal program name.
649 */
650 QString appName() const;
651
652 /**
653 * Returns the application's product name, which will be used in KBugReport
654 * dialog. By default it returns appName(), otherwise the one which is set
655 * with setProductName()
656 *
657 * @return the product name.
658 */
659 QString productName() const;
660
661 /**
662 * Returns the translated program name.
663 * @return the program name (translated).
664 */
665 QString programName() const;
666
667 /**
668 * Returns the domain name of the organization that wrote this application.
669 *
670 * Used by the automatic registration to D-Bus done by KApplication and KUniqueApplication.
671 */
672 QString organizationDomain() const;
673
674 /**
675 * @internal
676 * Provided for use by KCrash
677 */
678 const char* internalProgramName() const;
679
680 /**
681 * @internal
682 * Provided for use by KCrash
683 */
684 void translateInternalProgramName() const;
685
686 /**
687 * Returns the program's icon name.
688 *
689 * The default value is appName().
690 * Use setProgramIconName() if you need to have an icon
691 * whose name is different from the internal application name.
692 *
693 * @return the program's icon name.
694 * @see setProgramIconName()
695 * @since 4.1
696 */
697 QString programIconName() const;
698
699 /**
700 * Returns the program logo image.
701 *
702 * Because KAboutData is in kdecore it cannot use QImage directly,
703 * so this is a QVariant containing a QImage.
704 *
705 * @return the program logo data, or a null image if there is
706 * no custom application logo defined.
707 */
708 QVariant programLogo() const;
709
710 /**
711 * Returns the chosen Open Collaboration Services provider URL.
712 * @return the provider URL.
713 */
714 QString ocsProviderUrl() const;
715
716 /**
717 * Returns the program's version.
718 * @return the version string.
719 */
720 QString version() const;
721
722 /**
723 * @internal
724 * Provided for use by KCrash
725 */
726 const char* internalVersion() const;
727
728 /**
729 * Returns a short, translated description.
730 * @return the short description (translated). Can be
731 * QString() if not set.
732 */
733 QString shortDescription() const;
734
735 /**
736 * Returns the program's translation catalog name.
737 * @return the catalog name.
738 */
739 QString catalogName() const;
740
741 /**
742 * Returns the application homepage.
743 * @return the application homepage URL. Can be QString() if
744 * not set.
745 */
746 QString homepage() const;
747
748 /**
749 * Returns the email address for bugs.
750 * @return the email address where to report bugs.
751 */
752 QString bugAddress() const;
753
754 /**
755 * @internal
756 * Provided for use by KCrash
757 */
758 const char* internalBugAddress() const;
759
760 /**
761 * Returns a list of authors.
762 * @return author information (list of persons).
763 */
764 QList<KAboutPerson> authors() const;
765
766 /**
767 * Returns a list of persons who contributed.
768 * @return credit information (list of persons).
769 */
770 QList<KAboutPerson> credits() const;
771
772 /**
773 * Returns a list of translators.
774 * @return translators information (list of persons)
775 */
776 QList<KAboutPerson> translators() const;
777
778 /**
779 * Returns a message about the translation team.
780 * @return a message about the translation team
781 */
782 static QString aboutTranslationTeam();
783
784 /**
785 * Returns a translated, free form text.
786 * @return the free form text (translated). Can be QString() if not set.
787 */
788 QString otherText() const;
789
790 /**
791 * Returns the license. If the licenseType argument of the constructor has been
792 * used, any text defined by setLicenseText is ignored,
793 * and the standard text for the chosen license will be returned.
794 *
795 * @return The license text.
796 *
797 * @deprecated There could be multiple licenses, use licenses() instead.
798 */
799 QString license() const;
800
801 /**
802 * Returns the license name.
803 *
804 * @return The license name as a string.
805 *
806 * @deprecated There could be multiple licenses, use licenses() instead.
807 */
808 QString licenseName(NameFormat formatName) const;
809
810 /**
811 * Returns a list of licenses.
812 *
813 * @return licenses information (list of licenses)
814 * @since 4.1
815 */
816 QList<KAboutLicense> licenses() const;
817
818 /**
819 * Returns the copyright statement.
820 * @return the copyright statement. Can be QString() if not set.
821 */
822 QString copyrightStatement() const;
823
824 /**
825 * Returns the plain text displayed around the list of authors instead
826 * of the default message telling users to send bug reports to bugAddress().
827 *
828 * @return the plain text displayed around the list of authors instead
829 * of the default message. Can be QString().
830 */
831 QString customAuthorPlainText() const;
832
833 /**
834 * Returns the rich text displayed around the list of authors instead
835 * of the default message telling users to send bug reports to bugAddress().
836 *
837 * @return the rich text displayed around the list of authors instead
838 * of the default message. Can be QString().
839 */
840 QString customAuthorRichText() const;
841
842 /**
843 * Returns whether custom text should be displayed around the list of
844 * authors.
845 *
846 * @return whether custom text should be displayed around the list of
847 * authors.
848 */
849 bool customAuthorTextEnabled() const;
850
851 /**
852 * Sets the custom text displayed around the list of authors instead
853 * of the default message telling users to send bug reports to bugAddress().
854 *
855 * @param plainText The plain text.
856 * @param richText The rich text.
857 *
858 * Setting both to parameters to KLocalizedString() will cause no message to be
859 * displayed at all. Call unsetCustomAuthorText() to revert to the default
860 * message.
861 */
862 KAboutData &setCustomAuthorText(const KLocalizedString &plainText,
863 const KLocalizedString &richText);
864
865 /**
866 * Clears any custom text displayed around the list of authors and falls
867 * back to the default message telling users to send bug reports to
868 * bugAddress().
869 */
870 KAboutData &unsetCustomAuthorText();
871
872 private:
873
874 class Private;
875 Private *const d;
876};
877
878
879/**
880 * This class is used to store information about a license.
881 * The license can be one of some predefined, one given as text or one
882 * that can be loaded from a file. This class is used in the KAboutData class.
883 * Explicitly creating a KAboutLicense object is not possible.
884 * If the license is wanted for a KDE component having KAboutData object,
885 * use KAboutData::licenses() to get the licenses for that component.
886 * If the license is for a non-code resource and given by a keyword
887 * (e.g. in .desktop files), try using KAboutLicense::byKeyword().
888 *
889 * @note Instead of the more usual i18n calls, for translatable text the ki18n
890 * calls are used to produce KLocalizedStrings, which can delay the translation
891 * lookup. This is necessary because the translation catalogs are usually not
892 * yet initialized at the point where KAboutData is constructed.
893 */
894class KDECORE_EXPORT KAboutLicense
895{
896 friend class KAboutData;
897public:
898 /**
899 * Copy constructor. Performs a deep copy.
900 * @param other object to copy
901 */
902 KAboutLicense(const KAboutLicense& other);
903
904 ~KAboutLicense();
905
906 /**
907 * Assignment operator. Performs a deep copy.
908 * @param other object to copy
909 */
910 KAboutLicense& operator=(const KAboutLicense& other);
911
912
913 /**
914 * Returns the full license text. If the licenseType argument of the
915 * constructor has been used, any text defined by setLicenseText is ignored,
916 * and the standard text for the chosen license will be returned.
917 *
918 * @return The license text.
919 */
920 QString text() const;
921
922 /**
923 * Returns the license name.
924 *
925 * @return The license name as a string.
926 */
927 QString name(KAboutData::NameFormat formatName) const;
928
929 /**
930 * Returns the license key.
931 *
932 * @return The license key as element of KAboutData::LicenseKey enum.
933 * @since 4.1
934 */
935 KAboutData::LicenseKey key() const;
936
937 /**
938 * Fetch a known license by a keyword.
939 *
940 * Frequently the license data is provided by a terse keyword-like string,
941 * e.g. by a field in a .desktop file. Using this method, an application
942 * can get hold of a proper KAboutLicense object, providing that the
943 * license is one of the several known to KDE, and use it to present
944 * more human-readable information to the user.
945 *
946 * Keywords are matched by stripping all whitespace and lowercasing.
947 * The known keywords correspond to the KAboutData::LicenseKey enumeration,
948 * e.g. any of "LGPLV3", "LGPLv3", "LGPL v3" would match License_LGPL_V3.
949 * If there is no match for the keyword, a valid license object is still
950 * returned, with its name and text informing about a custom license,
951 * and its key equal to KAboutData::License_Custom.
952 *
953 * @param keyword The license keyword.
954 * @return The license object.
955 *
956 * @see KAboutData::LicenseKey
957 * @since 4.1
958 */
959 static KAboutLicense byKeyword(const QString &keyword);
960
961private:
962 /**
963 * @internal Used by KAboutData to construct a predefined license.
964 */
965 explicit KAboutLicense( enum KAboutData::LicenseKey licenseType, const KAboutData *aboutData );
966 /**
967 * @internal Used by KAboutData to construct license by given text
968 */
969 explicit KAboutLicense( const QString &pathToFile, const KAboutData *aboutData );
970 /**
971 * @internal Used by KAboutData to construct license by given text
972 */
973 explicit KAboutLicense( const KLocalizedString &licenseText, const KAboutData *aboutData );
974
975 class Private;
976 QSharedDataPointer<Private> d;
977};
978
979#endif
980
981