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
38class QLabel;
39class QLabel;
40class K3AboutContainer;
41class K3AboutContainerBase;
42
43/**
44 * K3AboutContainer can be used to make a application specific AboutDialog.
45 */
46class 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 showHeader = 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 */
82class 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 showHeader = false, bool showFrame = true,
93 bool showBold = false );
94
95 ~K3AboutContributor();
96
97 void setName( const QString &text, const QString &header = QString(),
98 bool update = true );
99
100 void setEmail( const QString &text, const QString &header = QString(),
101 bool update = true );
102
103 void setUrl( const QString &text, const QString &header = QString(),
104 bool update = true );
105
106 void setWork( const QString &text, const QString &header = 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 */
131class 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 & );
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 *;
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 */
255class 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 & );
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