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 |
38 | KTitleWidget *titleWidget = new KTitleWidget(this); |
39 | titleWidget->setText(i18n("Title")); |
40 | titleWidget->setPixmap(KIcon("screen").pixmap(22, 22), KTitleWidget::ImageLeft); |
41 | * @endcode |
42 | * |
43 | * Use it with an own widget: |
44 | * @code |
45 | KTitleWidget *checkboxTitleWidget = new KTitleWidget(this); |
46 | |
47 | QWidget *checkBoxTitleMainWidget = new QWidget(this); |
48 | QVBoxLayout *titleLayout = new QVBoxLayout(checkBoxTitleMainWidget); |
49 | titleLayout->setMargin(6); |
50 | |
51 | QCheckBox *checkBox = new QCheckBox("Text Checkbox", checkBoxTitleMainWidget); |
52 | titleLayout->addWidget(checkBox); |
53 | |
54 | checkboxTitleWidget->setWidget(checkBoxTitleMainWidget); |
55 | * @endcode |
56 | * |
57 | * @see KPageView |
58 | * @author Urs Wolfer \<uwolfer @ kde.org\> |
59 | */ |
60 | |
61 | class 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 | |
70 | public: |
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 () 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 | |
137 | public 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 (const QString &, 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 | |
196 | protected: |
197 | void changeEvent(QEvent *e); |
198 | void showEvent(QShowEvent *event); |
199 | bool eventFilter(QObject *object, QEvent *event); |
200 | |
201 | private: |
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 | |