1/* This file is part of the KDE libraries
2 Copyright (C) 2007-2009 Urs Wolfer <uwolfer @ kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18
19#ifndef KTITLEWIDGET_H
20#define KTITLEWIDGET_H
21
22#include <kdeui_export.h>
23
24#include <QtGui/QWidget>
25
26/**
27 * @short Standard title widget with a white background and round border.
28 *
29 * This class provides a widget often used for dialog titles.
30 * \image html ktitlewidget.png "KTitleWidget with title and icon"
31 *
32 * @section Usage
33 * KTitleWidget is very simple to use. You can either use its default text
34 * (and pixmap) properties or display your own widgets in the title widget.
35 *
36 * A title text with a left aligned pixmap:
37 * @code
38KTitleWidget *titleWidget = new KTitleWidget(this);
39titleWidget->setText(i18n("Title"));
40titleWidget->setPixmap(KIcon("screen").pixmap(22, 22), KTitleWidget::ImageLeft);
41 * @endcode
42 *
43 * Use it with an own widget:
44 * @code
45KTitleWidget *checkboxTitleWidget = new KTitleWidget(this);
46
47QWidget *checkBoxTitleMainWidget = new QWidget(this);
48QVBoxLayout *titleLayout = new QVBoxLayout(checkBoxTitleMainWidget);
49titleLayout->setMargin(6);
50
51QCheckBox *checkBox = new QCheckBox("Text Checkbox", checkBoxTitleMainWidget);
52titleLayout->addWidget(checkBox);
53
54checkboxTitleWidget->setWidget(checkBoxTitleMainWidget);
55 * @endcode
56 *
57 * @see KPageView
58 * @author Urs Wolfer \<uwolfer @ kde.org\>
59 */
60
61class KDEUI_EXPORT KTitleWidget : public QWidget
62{
63 Q_OBJECT
64 Q_ENUMS(ImageAlignment)
65 Q_PROPERTY(QString text READ text WRITE setText)
66 Q_PROPERTY(QString comment READ comment WRITE setComment)
67 Q_PROPERTY(QPixmap pixmap READ pixmap WRITE setPixmap)
68 Q_PROPERTY(int autoHideTimeout READ autoHideTimeout WRITE setAutoHideTimeout)
69
70public:
71 /**
72 * Possible title pixmap alignments.
73 *
74 * @li ImageLeft: Display the pixmap left
75 * @li ImageRight: Display the pixmap right (default)
76 */
77 enum ImageAlignment {
78 ImageLeft, /**< Display the pixmap on the left */
79 ImageRight /**< Display the pixmap on the right */
80 };
81
82 /**
83 * Comment message types
84 */
85 enum MessageType {
86 PlainMessage, /**< Normal comment */
87 InfoMessage, /**< Information the user should be alerted to */
88 WarningMessage, /**< A warning the user should be alerted to */
89 ErrorMessage /**< An error message */
90 };
91
92 /**
93 * Constructs a title widget with the given @param parent.
94 */
95 explicit KTitleWidget(QWidget *parent = 0);
96
97 virtual ~KTitleWidget();
98
99 /**
100 * @param widget Widget displayed on the title widget.
101 */
102 void setWidget(QWidget *widget);
103
104 /**
105 * @return the text displayed in the title
106 * @see setText()
107 */
108 QString text() const;
109
110 /**
111 * @return the text displayed in the comment below the title, if any
112 * @see setComment()
113 */
114 QString comment() const;
115
116 /**
117 * @return the pixmap displayed in the title
118 * @see setPixmap()
119 */
120 const QPixmap *pixmap() const;
121
122 /**
123 * Sets this label's buddy to buddy.
124 * When the user presses the shortcut key indicated by the label in this
125 * title widget, the keyboard focus is transferred to the label's buddy
126 * widget.
127 * @param buddy the widget to activate when the shortcut key is activated
128 */
129 void setBuddy(QWidget *buddy);
130
131 /**
132 * Get the current timeout value in milliseconds
133 * @return timeout value in msecs
134 */
135 int autoHideTimeout() const;
136
137public Q_SLOTS:
138 /**
139 * @param text Text displayed on the label. It can either be plain text or rich text. If it
140 * is plain text, the text is displayed as a bold title text.
141 * @param alignment Alignment of the text. Default is left and vertical centered.
142 * @see text()
143 */
144 void setText(const QString &text, Qt::Alignment alignment = Qt::AlignLeft | Qt::AlignVCenter);
145 /**
146 * @param text Text displayed on the label. It can either be plain text or rich text. If it
147 * is plain text, the text is displayed as a bold title text.
148 * @param type The sort of message it is; will also set the icon accordingly @see MessageType
149 * @see text()
150 */
151 void setText(const QString &text, MessageType type);
152
153 /**
154 * @param comment Text displayed beneath the main title as a comment.
155 * It can either be plain text or rich text.
156 * @param type The sort of message it is. @see MessageType
157 * @see comment()
158 */
159 void setComment(const QString &comment, MessageType type = PlainMessage);
160
161 /**
162 * @param pixmap Pixmap displayed in the header. The pixmap is by default right, but
163 * @param alignment can be used to display it also left.
164 * @see pixmap()
165 */
166 void setPixmap(const QPixmap &pixmap, ImageAlignment alignment = ImageRight);
167
168 /**
169 * @param icon name of the icon to display in the header. The pixmap is by default right, but
170 * @param alignment can be used to display it also left.
171 * @see pixmap()
172 */
173 void setPixmap(const QString &icon, ImageAlignment alignment = ImageRight);
174
175 /**
176 * @param pixmap the icon to display in the header. The pixmap is by default right, but
177 * @param alignment can be used to display it also left.
178 * @see pixmap()
179 */
180 void setPixmap(const QIcon& icon, ImageAlignment alignment = ImageRight);
181
182 /**
183 * @param pixmap the icon to display in the header. The pixmap is by default right, but
184 * @param alignment can be used to display it also left.
185 * @see pixmap()
186 */
187 void setPixmap(MessageType type, ImageAlignment alignment = ImageRight);
188
189 /**
190 * Set the autohide timeout of the label
191 * Set value to 0 to disable autohide, which is the default.
192 * @param msecs timeout value in milliseconds
193 */
194 void setAutoHideTimeout(int msecs);
195
196protected:
197 void changeEvent(QEvent *e);
198 void showEvent(QShowEvent *event);
199 bool eventFilter(QObject *object, QEvent *event);
200
201private:
202 class Private;
203 Private* const d;
204
205 Q_PRIVATE_SLOT(d, void _k_timeoutFinished())
206 Q_DISABLE_COPY(KTitleWidget)
207};
208
209#endif
210