1 | /* |
2 | * This file is part of the KDE Libraries |
3 | * Copyright (C) 1999-2001 Mirko Boehm (mirko@kde.org) and |
4 | * Espen Sand (espen@kde.org) |
5 | * |
6 | * This library is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Library General Public |
8 | * License as published by the Free Software Foundation; either |
9 | * version 2 of the License, or (at your option) any later version. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Library General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | * |
21 | */ |
22 | |
23 | /* |
24 | * This file declares a class for creating "About ..." dialogs |
25 | * in a general way. It provides geometry management and some |
26 | * options to connect for, like emailing the author or maintainer. |
27 | */ |
28 | |
29 | |
30 | #ifndef K3ABOUTDIALOG_H |
31 | #define K3ABOUTDIALOG_H |
32 | |
33 | #include <kde3support_export.h> |
34 | |
35 | #include <QtGui/QFrame> |
36 | #include <kdialog.h> |
37 | |
38 | class QLabel; |
39 | class QLabel; |
40 | class K3AboutContainer; |
41 | class K3AboutContainerBase; |
42 | |
43 | /** |
44 | * K3AboutContainer can be used to make a application specific AboutDialog. |
45 | */ |
46 | class KDE3SUPPORT_EXPORT K3AboutContainer : public QFrame |
47 | { |
48 | Q_OBJECT |
49 | |
50 | public: |
51 | K3AboutContainer( QWidget *parent = 0, |
52 | int margin = 0, int spacing = 0, |
53 | Qt::Alignment childAlignment = Qt::AlignCenter, |
54 | Qt::Alignment innerAlignment = Qt::AlignCenter ); |
55 | |
56 | ~K3AboutContainer(); |
57 | |
58 | void addWidget( QWidget *widget ); |
59 | |
60 | void addPerson( const QString &name, const QString &email, |
61 | const QString &url, const QString &task, |
62 | bool = false, bool showframe = false, |
63 | bool showBold = false ); |
64 | |
65 | void addTitle( const QString &title, Qt::Alignment alignment = Qt::AlignLeft, |
66 | bool showframe = false, bool showBold = false ); |
67 | |
68 | void addImage( const QString &fileName, Qt::Alignment alignment = Qt::AlignLeft ); |
69 | |
70 | virtual QSize sizeHint() const; |
71 | virtual QSize minimumSizeHint() const; |
72 | |
73 | private: |
74 | class Private; |
75 | Private* const d; |
76 | }; |
77 | |
78 | /** |
79 | * Used internally by K3AboutWidget |
80 | * @internal |
81 | */ |
82 | class KDE3SUPPORT_EXPORT K3AboutContributor : public QFrame |
83 | { |
84 | Q_OBJECT |
85 | |
86 | public: |
87 | K3AboutContributor( QWidget *parent = 0, |
88 | const QString &username = QString(), |
89 | const QString &email = QString(), |
90 | const QString &url = QString(), |
91 | const QString &work = QString(), |
92 | bool = false, bool showFrame = true, |
93 | bool showBold = false ); |
94 | |
95 | ~K3AboutContributor(); |
96 | |
97 | void setName( const QString &text, const QString & = QString(), |
98 | bool update = true ); |
99 | |
100 | void setEmail( const QString &text, const QString & = QString(), |
101 | bool update = true ); |
102 | |
103 | void setUrl( const QString &text, const QString & = QString(), |
104 | bool update = true ); |
105 | |
106 | void setWork( const QString &text, const QString & = QString(), |
107 | bool update = true ); |
108 | |
109 | QString name() const; |
110 | QString email() const; |
111 | QString url() const; |
112 | QString work() const; |
113 | |
114 | virtual QSize sizeHint() const; |
115 | |
116 | protected: |
117 | virtual void fontChange( const QFont &oldFont ); |
118 | |
119 | private: |
120 | class Private; |
121 | Private* const d; |
122 | |
123 | virtual void setName(const char *_name) { QObject::setObjectName(QLatin1String(_name)); } |
124 | }; |
125 | |
126 | /** |
127 | * K3AboutWidget is the main widget for K3AboutDialog. |
128 | * |
129 | * It has a minimum size set. |
130 | */ |
131 | class KDE3SUPPORT_EXPORT K3AboutWidget : public QWidget |
132 | { |
133 | Q_OBJECT |
134 | |
135 | public: |
136 | |
137 | /** |
138 | * Creates a new about widget. |
139 | */ |
140 | K3AboutWidget( QWidget* parent=0 ); |
141 | |
142 | /** |
143 | * Adjust the minimum size (after setting the properties of the image and |
144 | * the labels. |
145 | */ |
146 | void adjust(); |
147 | |
148 | /** |
149 | * Sets the image as the application logo. |
150 | * |
151 | * @param logo The application logo |
152 | */ |
153 | void setLogo( const QPixmap &logo ); |
154 | |
155 | /** |
156 | * Sets the author's name and email address. |
157 | */ |
158 | void setAuthor( const QString& name, const QString& email, |
159 | const QString& url, const QString& work ); |
160 | |
161 | /** |
162 | * Sets the maintainers name and email address. |
163 | */ |
164 | void setMaintainer( const QString& name, const QString& email, |
165 | const QString& url, const QString& work ); |
166 | |
167 | /** |
168 | * Shows this person as one of the major contributors. |
169 | */ |
170 | void addContributor( const QString& name, const QString& email, |
171 | const QString& url, const QString& work ); |
172 | |
173 | /** |
174 | * Sets the text describing the version. |
175 | */ |
176 | void setVersion( const QString& name ); |
177 | |
178 | protected: |
179 | /** |
180 | * The resize event. |
181 | */ |
182 | void resizeEvent(QResizeEvent*); |
183 | |
184 | /** |
185 | * The label showing the program version. |
186 | */ |
187 | QLabel *version; |
188 | |
189 | /** |
190 | * The label showing the text "Other contributors:". |
191 | */ |
192 | QLabel *cont; |
193 | |
194 | /** |
195 | * The frame showing the logo. |
196 | */ |
197 | QLabel *logo; |
198 | |
199 | /** |
200 | * The application developer. |
201 | */ |
202 | K3AboutContributor *author; |
203 | |
204 | /** |
205 | * The application maintainer. |
206 | */ |
207 | K3AboutContributor *maintainer; |
208 | |
209 | /** |
210 | * Show the maintainer? |
211 | */ |
212 | bool showMaintainer; |
213 | |
214 | /** |
215 | * A set of people who contributed to the application. |
216 | */ |
217 | QList<K3AboutContributor *> contributors; |
218 | |
219 | private: |
220 | class Private; |
221 | Private* const d; |
222 | }; |
223 | |
224 | /** |
225 | * A KDialog with predefined main widget. |
226 | * |
227 | * As a KDialog it uses your application wide settings |
228 | * for KDialog |
229 | * objects (base frame tiles, main frame tiles etc). |
230 | * To use it, simply create a K3AboutDialog object, set all (or some) of its |
231 | * properties and show it. Do not derive it to create your own about dialog |
232 | * until you need some cool features that are unsupported and you have |
233 | * contacted me to add them. |
234 | * |
235 | * The dialog can be created using two different constructors. The |
236 | * difference between these constructors is the available components that |
237 | * can be used to build the contents of the dialog. The first (Constructor I) |
238 | * provides a number of easy to use methods. Basically it allows you |
239 | * to add the components of choice, and the components are placed in a |
240 | * predefined layout. You do not have to plan the layout. Everything is |
241 | * taken care of. |
242 | * |
243 | * The second constructor (Constructor II) works in quite the same manner |
244 | * as the first, but you have better control on where the components |
245 | * are postioned in the layout and you have access to an extended number |
246 | * of components you can install such as titles, product information, |
247 | * a tabbed pages (where you can display rich text with url links) and |
248 | * a person (developer) information field. The "About KDE" dialog box is |
249 | * created with Constructor II. |
250 | * |
251 | * For the derived features, see the basic class KDialog. |
252 | * @author Mirko Boehm (mirko@kde.org) and Espen Sand (espensa@online.no) |
253 | * @see KDialog |
254 | */ |
255 | class KDE3SUPPORT_EXPORT K3AboutDialog : public KDialog |
256 | { |
257 | Q_OBJECT |
258 | |
259 | public: |
260 | |
261 | /** |
262 | * Layout formats. |
263 | **/ |
264 | enum LayoutType |
265 | { |
266 | Plain = 0x0001, |
267 | Tabbed = 0x0002, |
268 | Title = 0x0004, |
269 | ImageLeft = 0x0008, |
270 | ImageRight = 0x0010, |
271 | ImageOnly = 0x0020, |
272 | Product = 0x0040, |
273 | KDEStandard = Tabbed | Title | ImageLeft, |
274 | AppStandard = Tabbed | Title | Product, |
275 | ImageAndTitle = Plain | Title | ImageOnly |
276 | }; |
277 | |
278 | public: |
279 | /** |
280 | * The standard Qt constructor (Constructor I). |
281 | * |
282 | * Add components with the following methods: |
283 | * setLogo(), setAuthor(), setMaintainer(), |
284 | * addContributor(), or setVersion(). |
285 | * The dialog will be laid out automatically. |
286 | */ |
287 | K3AboutDialog( QWidget *parent=0 ); |
288 | |
289 | /** |
290 | * The extended constructor. (Constructor II). |
291 | * |
292 | * Add components with the methods: |
293 | * setTitle(), setImage(), setImageBackgroundColor(), |
294 | * setImageFrame(), setProduct(), addTextPage(), |
295 | * addContainerPage(), addContainer(), or addPage(). |
296 | * |
297 | * @param dialogLayout Use a mask of LayoutType flags. |
298 | * @param caption The dialog caption. The text you specify is prepended |
299 | * by i18n("About"). |
300 | * @param parent Parent of the dialog. |
301 | */ |
302 | K3AboutDialog( int dialogLayout, const QString &caption, QWidget *parent=0 ); |
303 | |
304 | /** |
305 | * Adjusts the dialog. |
306 | * |
307 | * You can call this method after you have set up all |
308 | * the contents but it is not required. It is done automatically when |
309 | * show() is executed. |
310 | */ |
311 | void adjust(); |
312 | |
313 | /** |
314 | * Makes a modeless dialog visible. |
315 | * |
316 | * If you reimplement this method make sure you run it |
317 | * in the new method (e.g., show()). Reimplemented |
318 | * from KDialog. |
319 | */ |
320 | virtual void show(); |
321 | |
322 | /** |
323 | * Makes a modeless dialog visible. |
324 | * |
325 | * If you reimplmement this method make sure you run it |
326 | * in the new method (i.e., show( parent )). |
327 | * |
328 | * @param centerParent Center the dialog with respect to this widget. |
329 | */ |
330 | virtual void show( QWidget *centerParent ); |
331 | |
332 | /** |
333 | * (Constructor II only) |
334 | * Sets a title (not caption) in the uppermost area of the dialog. |
335 | * |
336 | * @param title Title string. |
337 | */ |
338 | void setTitle( const QString &title ); |
339 | |
340 | /** |
341 | * (Constructor II only) |
342 | * Define an image to be shown in the dialog. The position is dependent |
343 | * on the @p dialogLayout in the constructor |
344 | * |
345 | * @param fileName Path to image file. |
346 | */ |
347 | void setImage( const QString &fileName ); |
348 | |
349 | /** |
350 | * Overloaded version of setProgramLogo(const QPixmap& pixmap). |
351 | */ |
352 | void setProgramLogo( const QString &fileName ); |
353 | |
354 | /** |
355 | * (Constructor II only) |
356 | * Define the program logo to be shown in the dialog. Use this to override the |
357 | * default program logo. For example, use this function if the |
358 | * K3AboutDialog is for a panel applet and you want to override the |
359 | * appletproxy logo with your own pixmap. |
360 | * |
361 | * @param pixmap The logo pixmap. |
362 | */ |
363 | void setProgramLogo( const QPixmap &pixmap ); |
364 | |
365 | /** |
366 | * (Constructor II only) |
367 | * The image has a minimum size, but is centered within an area if the |
368 | * dialog box is enlarged by the user. You set the background color |
369 | * of the area with this method. |
370 | * |
371 | * @param color Background color. |
372 | */ |
373 | void setImageBackgroundColor( const QColor &color ); |
374 | |
375 | /** |
376 | * (Constructor II only) |
377 | * Enables or disables a frame around the image. The frame is, by default, |
378 | * enabled in the constructor |
379 | * |
380 | * @param state A value of @p true enables the frame |
381 | */ |
382 | void setImageFrame( bool state ); |
383 | |
384 | /** |
385 | * (Constructor II only) |
386 | * Prints the application name, KDE version, author, a copyright sign |
387 | * and a year string. To the left of the text the standard application |
388 | * icon is displayed. |
389 | * |
390 | * @param appName The application name. |
391 | * @param version Application version. |
392 | * @param author One or more authors. |
393 | * @param year A string telling when the application was made. |
394 | */ |
395 | void setProduct( const QString &appName, const QString &version, |
396 | const QString &author, const QString &year ); |
397 | |
398 | /** |
399 | * (Constructor II only) |
400 | * Adds a text page to a tab box. The text can be regular text or |
401 | * rich text. The rich text can contain URLs and mail links. |
402 | * |
403 | * @param title Tab name. |
404 | * @param text The text to display. |
405 | * @param richText Set this to @p true if 'text' is rich text. |
406 | * @param numLines The text area height will be adjusted so that this |
407 | * is the minimum number of lines of text that are visible. |
408 | * @return The frame that contains the page. |
409 | */ |
410 | QFrame *addTextPage( const QString &title, const QString &text, |
411 | bool richText=false, int numLines=10 ); |
412 | |
413 | /** |
414 | * (Constructor II only) |
415 | * Adds a license page to a tab box. |
416 | * |
417 | * @param title Tab name. |
418 | * @param text The text to display. |
419 | * @param numLines The text area height will be adjusted so that this |
420 | * is the minimum number of lines of text that are visible. |
421 | * @return The frame that contains the page. |
422 | */ |
423 | QFrame *addLicensePage( const QString &title, const QString &text, |
424 | int numLines=10 ); |
425 | |
426 | /** |
427 | * (Constructor II only) |
428 | * Adds a container to a tab box. You can add text and images to a |
429 | * container. |
430 | * |
431 | * @param title Tab name. |
432 | * @param childAlignment Specifies how the children of the container are |
433 | * aligned with respect to the container. |
434 | * @param innerAlignment Specifies how the children are aligned with |
435 | * respect to each other. |
436 | * @return The new container. |
437 | */ |
438 | K3AboutContainer *addContainerPage( const QString &title, |
439 | Qt::Alignment childAlignment = Qt::AlignCenter, |
440 | Qt::Alignment innerAlignment = Qt::AlignCenter ); |
441 | |
442 | /** |
443 | * (Constructor II only) |
444 | * Adds a container inside a QScrollView to a tab box. You can add text |
445 | * and images to a container. |
446 | * |
447 | * @param title Tab name. |
448 | * @param childAlignment Specifies how the children of the container are |
449 | * aligned with respect to the container. |
450 | * @param innerAlignment Specifies how the children are aligned with |
451 | * respect to each other. |
452 | * @return The new container. |
453 | */ |
454 | K3AboutContainer *addScrolledContainerPage( const QString &title, |
455 | Qt::Alignment childAlignment = Qt::AlignCenter, |
456 | Qt::Alignment innerAlignment = Qt::AlignCenter ); |
457 | |
458 | /** |
459 | * (Constructor II only) |
460 | * Adds a container. You can add text and images to a container. |
461 | * |
462 | * @param childAlignment Specifies how the children of the container are |
463 | * aligned with respect to the container. |
464 | * @param innerAlignment Specifies how the children are aligned with |
465 | * respect to each other. |
466 | * @return The new container. |
467 | */ |
468 | K3AboutContainer *addContainer( Qt::Alignment childAlignment, Qt::Alignment innerAlignment ); |
469 | |
470 | /** |
471 | * (Constructor II only) |
472 | * Adds an empty page to a tab box. |
473 | * |
474 | * @param title Tab name |
475 | * @return The new page. |
476 | */ |
477 | QFrame *addPage( const QString &title ); |
478 | |
479 | /** |
480 | * (Constructor I only) |
481 | * Sets the image as the application logo. |
482 | */ |
483 | void setLogo( const QPixmap &logo ); |
484 | |
485 | /** |
486 | * (Constructor I only) |
487 | * Sets the author's name and email address. |
488 | */ |
489 | void setAuthor( const QString& name, const QString& email, |
490 | const QString& url, const QString& work ); |
491 | |
492 | /** |
493 | * (Constructor I only) |
494 | * Sets the maintainer's name and email address. |
495 | */ |
496 | void setMaintainer( const QString& name, const QString& email, |
497 | const QString& url, const QString& work ); |
498 | |
499 | /** |
500 | * (Constructor I only) |
501 | * Show this person as one of the major contributors. |
502 | */ |
503 | void addContributor( const QString& name, const QString& email, |
504 | const QString& url, const QString& work ); |
505 | |
506 | /** |
507 | * (Constructor I only) |
508 | * Sets the text describing the version. |
509 | */ |
510 | void setVersion( const QString& name ); |
511 | |
512 | /** |
513 | * Create a modal dialog with an image in the upper area with a |
514 | * URL link below. |
515 | */ |
516 | static void imageUrl( QWidget *parent, const QString &caption, |
517 | const QString &path, const QColor &imageColor, |
518 | const QString &url ); |
519 | |
520 | protected: |
521 | /** |
522 | * The main widget (Constructor I) |
523 | */ |
524 | K3AboutWidget *mAbout; |
525 | |
526 | /** |
527 | * The main widget (Constructor II) |
528 | */ |
529 | K3AboutContainerBase *mContainerBase; |
530 | |
531 | private: |
532 | class Private; |
533 | Private* const d; |
534 | }; |
535 | |
536 | #endif // defined K3ABOUTDIALOG_H |
537 | |