1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2007-2009 Urs Wolfer <uwolfer@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KTITLEWIDGET_H
9#define KTITLEWIDGET_H
10
11#include <kwidgetsaddons_export.h>
12
13#include <QWidget>
14#include <memory>
15
16/**
17 * @class KTitleWidget ktitlewidget.h KTitleWidget
18 *
19 * @short Standard title widget.
20 *
21 * This class provides a widget often used for dialog titles.
22 * \image html ktitlewidget.png "KTitleWidget with title and icon"
23 *
24 * KTitleWidget uses the general application font at 1.4 times its size to
25 * style the text. This is a visual change from 4.x.
26 *
27 * @section Usage
28 * KTitleWidget is very simple to use. You can either use its default text
29 * (and pixmap) properties or display your own widgets in the title widget.
30 *
31 * A title text with a right-aligned pixmap:
32 * @code
33KTitleWidget *titleWidget = new KTitleWidget(this);
34titleWidget->setText(i18n("Title"));
35titleWidget->setIcon(QIcon::fromTheme("screen"));
36 * @endcode
37 *
38 * Use it with an own widget:
39 * @code
40KTitleWidget *checkboxTitleWidget = new KTitleWidget(this);
41
42QWidget *checkBoxTitleMainWidget = new QWidget(this);
43QVBoxLayout *titleLayout = new QVBoxLayout(checkBoxTitleMainWidget);
44titleLayout->setContentsMargins(6, 6, 6, 6);
45
46QCheckBox *checkBox = new QCheckBox("Text Checkbox", checkBoxTitleMainWidget);
47titleLayout->addWidget(checkBox);
48
49checkboxTitleWidget->setWidget(checkBoxTitleMainWidget);
50 * @endcode
51 *
52 * @see KPageView
53 * @author Urs Wolfer \<uwolfer @ kde.org\>
54 */
55class KWIDGETSADDONS_EXPORT KTitleWidget : public QWidget
56{
57 Q_OBJECT
58 Q_PROPERTY(QString text READ text WRITE setText)
59 Q_PROPERTY(QString comment READ comment WRITE setComment)
60 /// @since 5.72
61 Q_PROPERTY(QIcon icon READ icon WRITE setIcon)
62 /// @since 5.72
63 Q_PROPERTY(QSize iconSize READ iconSize WRITE setIconSize)
64 Q_PROPERTY(int autoHideTimeout READ autoHideTimeout WRITE setAutoHideTimeout)
65
66public:
67 /**
68 * Possible title pixmap alignments.
69 *
70 * @li ImageLeft: Display the pixmap left
71 * @li ImageRight: Display the pixmap right (default)
72 */
73 enum ImageAlignment {
74 ImageLeft, /**< Display the pixmap on the left */
75 ImageRight, /**< Display the pixmap on the right */
76 };
77 Q_ENUM(ImageAlignment)
78
79 /**
80 * Comment message types
81 */
82 enum MessageType {
83 PlainMessage, /**< Normal comment */
84 InfoMessage, /**< Information the user should be alerted to */
85 WarningMessage, /**< A warning the user should be alerted to */
86 ErrorMessage, /**< An error message */
87 };
88
89 /**
90 * Constructs a title widget.
91 */
92 explicit KTitleWidget(QWidget *parent = nullptr);
93
94 ~KTitleWidget() override;
95
96 /**
97 * @param widget Widget displayed on the title widget.
98 */
99 void setWidget(QWidget *widget);
100
101 /**
102 * @return the text displayed in the title
103 * @see setText()
104 */
105 QString text() const;
106
107 /**
108 * @return the text displayed in the comment below the title, if any
109 * @see setComment()
110 */
111 QString comment() const;
112
113 /**
114 * @return the icon displayed in the title
115 * @see setIcon()
116 *
117 * @since 5.72
118 */
119 QIcon icon() const;
120
121 /**
122 * @return the size of the icon displayed in the title
123 * @see setIconSize()
124 *
125 * @since 5.72
126 */
127 QSize iconSize() const;
128
129 /**
130 * Sets this label's buddy to buddy.
131 * When the user presses the shortcut key indicated by the label in this
132 * title widget, the keyboard focus is transferred to the label's buddy
133 * widget.
134 * @param buddy the widget to activate when the shortcut key is activated
135 */
136 void setBuddy(QWidget *buddy);
137
138 /**
139 * Get the current timeout value in milliseconds
140 * @return timeout value in msecs
141 */
142 int autoHideTimeout() const;
143
144 /**
145 * @return The level of this title: it influences the font size following the guidelines in
146 * the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>.
147 * It also corresponds to the level api of Kirigami Heading for QML applications
148 * @since 5.53
149 */
150 int level();
151
152public Q_SLOTS:
153 /**
154 * @param text Text displayed on the label. It can either be plain text or rich text. If it
155 * is plain text, the text is displayed as a bold title text.
156 * @param alignment Alignment of the text. Default is left and vertical centered.
157 * @see text()
158 */
159 void setText(const QString &text, Qt::Alignment alignment = Qt::AlignLeft | Qt::AlignVCenter);
160 /**
161 * @param text Text displayed on the label. It can either be plain text or rich text. If it
162 * is plain text, the text is displayed as a bold title text.
163 * @param type The sort of message it is; will also set the icon accordingly
164 * @see text()
165 */
166 void setText(const QString &text, MessageType type);
167
168 /**
169 * @param comment Text displayed beneath the main title as a comment.
170 * It can either be plain text or rich text.
171 * @param type The sort of message it is.
172 * @see comment()
173 */
174 void setComment(const QString &comment, MessageType type = PlainMessage);
175
176 /**
177 * Set the icon to display in the header.
178 * @param icon the icon to display in the header.
179 * @param alignment alignment of the icon (default is right aligned).
180 * @since 5.63
181 */
182 void setIcon(const QIcon &icon, ImageAlignment alignment = ImageRight);
183
184 /**
185 * @param type the type of message icon to display in the header
186 * @param alignment alignment of the icon (default is right aligned).
187 * @see icon()
188 * @since 5.72
189 */
190 void setIcon(MessageType type, ImageAlignment alignment = ImageRight);
191
192 /**
193 * Set the size of the icon to display in the header.
194 * @param iconSize the size of the icon, or an invalid QSize to reset to the default
195 *
196 * The default size is defined by the GUI style and its value for QStyle::PM_MessageBoxIconSize.
197 *
198 * @since 5.72
199 */
200 void setIconSize(const QSize &iconSize);
201
202 /**
203 * Set the autohide timeout of the label
204 * Set value to 0 to disable autohide, which is the default.
205 * @param msecs timeout value in milliseconds
206 */
207 void setAutoHideTimeout(int msecs);
208
209 /**
210 * Sets the level of this title, similar to HTML's h1 h2 h3...
211 * Follows the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>.
212 * @param level the level of the title, 1 is the biggest font and most important, descending
213 * @since 5.53
214 */
215 void setLevel(int level);
216
217protected:
218 void changeEvent(QEvent *e) override;
219 void showEvent(QShowEvent *event) override;
220 bool eventFilter(QObject *object, QEvent *event) override;
221
222private:
223 std::unique_ptr<class KTitleWidgetPrivate> const d;
224
225 Q_DISABLE_COPY(KTitleWidget)
226};
227
228#endif
229

source code of kwidgetsaddons/src/ktitlewidget.h