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 | |
33 | template <class T> class QList; |
34 | class QVariant; |
35 | class 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 | */ |
68 | class KDECORE_EXPORT KAboutPerson |
69 | { |
70 | friend class KAboutData; |
71 | public: |
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 | |
157 | private: |
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 | |
167 | class 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 | */ |
192 | class 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 ©rightStatement = 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 ©rightStatement ); |
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 | */ |
894 | class KDECORE_EXPORT KAboutLicense |
895 | { |
896 | friend class KAboutData; |
897 | public: |
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 | |
961 | private: |
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 | |