KDELibs4Support

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

KDE's Doxygen guidelines are available online.