KWidgetsAddons

ktitlewidget.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2007-2009 Urs Wolfer <[email protected]>
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
33 KTitleWidget *titleWidget = new KTitleWidget(this);
34 titleWidget->setText(i18n("Title"));
35 titleWidget->setIcon(QIcon::fromTheme("screen"));
36  * @endcode
37  *
38  * Use it with an own widget:
39  * @code
40 KTitleWidget *checkboxTitleWidget = new KTitleWidget(this);
41 
42 QWidget *checkBoxTitleMainWidget = new QWidget(this);
43 QVBoxLayout *titleLayout = new QVBoxLayout(checkBoxTitleMainWidget);
44 titleLayout->setContentsMargins(6, 6, 6, 6);
45 
46 QCheckBox *checkBox = new QCheckBox("Text Checkbox", checkBoxTitleMainWidget);
47 titleLayout->addWidget(checkBox);
48 
49 checkboxTitleWidget->setWidget(checkBoxTitleMainWidget);
50  * @endcode
51  *
52  * @see KPageView
53  * @author Urs Wolfer <uwolfer @ kde.org>
54  */
55 class 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 #if KWIDGETSADDONS_BUILD_DEPRECATED_SINCE(5, 72)
65  /// @deprecated Since 5.72, use property icon instead
66  Q_PROPERTY(QPixmap pixmap READ pixmap WRITE setPixmap)
67 #endif
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  */
78  ImageLeft, /**< Display the pixmap on the left */
79  ImageRight, /**< Display the pixmap on the right */
80  };
81  Q_ENUM(ImageAlignment)
82 
83  /**
84  * Comment message types
85  */
86  enum MessageType {
87  PlainMessage, /**< Normal comment */
88  InfoMessage, /**< Information the user should be alerted to */
89  WarningMessage, /**< A warning the user should be alerted to */
90  ErrorMessage, /**< An error message */
91  };
92 
93  /**
94  * Constructs a title widget.
95  */
96  explicit KTitleWidget(QWidget *parent = nullptr);
97 
98  ~KTitleWidget() override;
99 
100  /**
101  * @param widget Widget displayed on the title widget.
102  */
103  void setWidget(QWidget *widget);
104 
105  /**
106  * @return the text displayed in the title
107  * @see setText()
108  */
109  QString text() const;
110 
111  /**
112  * @return the text displayed in the comment below the title, if any
113  * @see setComment()
114  */
115  QString comment() const;
116 
117 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72)
118  /**
119  * @return the pixmap displayed in the title
120  * @see setPixmap()
121  * @deprecated Since 5.72, use icon()
122  */
123  KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::icon()")
124  const QPixmap *pixmap() const;
125 #endif
126 
127  /**
128  * @return the icon displayed in the title
129  * @see setIcon()
130  *
131  * @since 5.72
132  */
133  QIcon icon() const;
134 
135  /**
136  * @return the size of the icon displayed in the title
137  * @see setIconSize()
138  *
139  * @since 5.72
140  */
141  QSize iconSize() const;
142 
143  /**
144  * Sets this label's buddy to buddy.
145  * When the user presses the shortcut key indicated by the label in this
146  * title widget, the keyboard focus is transferred to the label's buddy
147  * widget.
148  * @param buddy the widget to activate when the shortcut key is activated
149  */
150  void setBuddy(QWidget *buddy);
151 
152  /**
153  * Get the current timeout value in milliseconds
154  * @return timeout value in msecs
155  */
156  int autoHideTimeout() const;
157 
158  /**
159  * @return The level of this title: it influences the font size following the guidelines in
160  * the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>.
161  * It also corresponds to the level api of Kirigami Heading for QML applications
162  * @since 5.53
163  */
164  int level();
165 
166 public Q_SLOTS:
167  /**
168  * @param text Text displayed on the label. It can either be plain text or rich text. If it
169  * is plain text, the text is displayed as a bold title text.
170  * @param alignment Alignment of the text. Default is left and vertical centered.
171  * @see text()
172  */
173  void setText(const QString &text, Qt::Alignment alignment = Qt::AlignLeft | Qt::AlignVCenter);
174  /**
175  * @param text Text displayed on the label. It can either be plain text or rich text. If it
176  * is plain text, the text is displayed as a bold title text.
177  * @param type The sort of message it is; will also set the icon accordingly
178  * @see text()
179  */
180  void setText(const QString &text, MessageType type);
181 
182  /**
183  * @param comment Text displayed beneath the main title as a comment.
184  * It can either be plain text or rich text.
185  * @param type The sort of message it is.
186  * @see comment()
187  */
188  void setComment(const QString &comment, MessageType type = PlainMessage);
189 
190  /**
191  * Set the icon to display in the header.
192  * @param icon the icon to display in the header.
193  * @param alignment alignment of the icon (default is right aligned).
194  * @since 5.63
195  */
196  void setIcon(const QIcon &icon, ImageAlignment alignment = ImageRight);
197 
198 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72)
199  /**
200  * Sets the icon to the @p pixmap and also the icon size to the size of the @p pixmap.
201  * @param pixmap Pixmap displayed in the header. The pixmap is by default right, but
202  * @param alignment can be used to display it also left.
203  * @see pixmap()
204  * @deprecated Since 5.72, use setIcon(const QIcon &, ImageAlignment)
205  */
206  KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)")
207  void setPixmap(const QPixmap &pixmap, ImageAlignment alignment = ImageRight);
208 #endif
209 
210 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 63)
211  /**
212  * @param icon name of the icon to display in the header. The pixmap is by default right, but
213  * @param alignment can be used to display it also left.
214  * @see pixmap()
215  * @deprecated since 5.63 use setIcon() instead
216  */
217  KWIDGETSADDONS_DEPRECATED_VERSION(5, 63, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)")
218  void setPixmap(const QString &icon, ImageAlignment alignment = ImageRight);
219 #endif
220 
221 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 63)
222  /**
223  * @param icon the icon to display in the header. The pixmap is by default right, but
224  * @param alignment can be used to display it also left.
225  * @see pixmap()
226  * @deprecated since 5.63 use setIcon() instead
227  */
228  KWIDGETSADDONS_DEPRECATED_VERSION(5, 63, "Use KTitleWidget::setIcon(const QIcon &, ImageAlignment)")
229  void setPixmap(const QIcon &icon, ImageAlignment alignment = ImageRight);
230 #endif
231 
232  /**
233  * @param type the type of message icon to display in the header
234  * @param alignment alignment of the icon (default is right aligned).
235  * @see icon()
236  * @since 5.72
237  */
238  void setIcon(MessageType type, ImageAlignment alignment = ImageRight);
239 
240 #if KWIDGETSADDONS_ENABLE_DEPRECATED_SINCE(5, 72)
241  /**
242  * @param type the type of message icon to display in the header. The pixmap is by default right, but
243  * @param alignment can be used to display it also left.
244  * @see pixmap()
245  * @deprecated Since 5.72 use setIcon(MessageType, ImageAlignment) instead
246  */
247  KWIDGETSADDONS_DEPRECATED_VERSION(5, 72, "Use KTitleWidget::setIcon(MessageType, ImageAlignment)")
248  void setPixmap(MessageType type, ImageAlignment alignment = ImageRight);
249 #endif
250 
251  /**
252  * Set the size of the icon to display in the header.
253  * @param iconSize the size of the icon, or an invalid QSize to reset to the default
254  *
255  * The default size is defined by the GUI style and its value for QStyle::PM_MessageBoxIconSize.
256  *
257  * @since 5.72
258  */
259  void setIconSize(const QSize &iconSize);
260 
261  /**
262  * Set the autohide timeout of the label
263  * Set value to 0 to disable autohide, which is the default.
264  * @param msecs timeout value in milliseconds
265  */
266  void setAutoHideTimeout(int msecs);
267 
268  /**
269  * Sets the level of this title, similar to HTML's h1 h2 h3...
270  * Follows the <a href="https://develop.kde.org/hig/style/typography/">KDE HIG</a>.
271  * @param level the level of the title, 1 is the biggest font and most important, descending
272  * @since 5.53
273  */
274  void setLevel(int level);
275 
276 protected:
277  void changeEvent(QEvent *e) override;
278  void showEvent(QShowEvent *event) override;
279  bool eventFilter(QObject *object, QEvent *event) override;
280 
281 private:
282  std::unique_ptr<class KTitleWidgetPrivate> const d;
283 
285 };
286 
287 #endif
typedef Alignment
Q_PROPERTY(...)
@ ImageRight
Display the pixmap on the right.
Definition: ktitlewidget.h:79
Q_ENUM(...)
@ ErrorMessage
An error message.
Definition: ktitlewidget.h:90
Q_SLOTSQ_SLOTS
@ ImageLeft
Display the pixmap on the left.
Definition: ktitlewidget.h:78
@ PlainMessage
Normal comment.
Definition: ktitlewidget.h:87
virtual void changeEvent(QEvent *event)
virtual bool eventFilter(QObject *watched, QEvent *event)
virtual void showEvent(QShowEvent *event)
Standard title widget.
Definition: ktitlewidget.h:55
@ InfoMessage
Information the user should be alerted to.
Definition: ktitlewidget.h:88
ImageAlignment
Possible title pixmap alignments.
Definition: ktitlewidget.h:77
Q_DISABLE_COPY(Class)
@ WarningMessage
A warning the user should be alerted to.
Definition: ktitlewidget.h:89
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Dec 11 2023 04:01:38 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.