1/* This file is part of the KDE libraries
2 *
3 * Copyright (c) 2011 Aurélien Gâteau <agateau@kde.org>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18 * 02110-1301 USA
19 */
20#ifndef KMESSAGEWIDGET_H
21#define KMESSAGEWIDGET_H
22
23#include <kdeui_export.h>
24
25#include <QFrame>
26
27class KMessageWidgetPrivate;
28
29/**
30 * @short A widget to provide feedback or propose opportunistic interactions.
31 *
32 * KMessageWidget can be used to provide inline positive or negative
33 * feedback, or to implement opportunistic interactions.
34 *
35 * As a feedback widget, KMessageWidget provides a less intrusive alternative
36 * to "OK Only" message boxes. If you do not need the modalness of KMessageBox,
37 * consider using KMessageWidget instead.
38 *
39 * <b>Negative feedback</b>
40 *
41 * The KMessageWidget can be used as a secondary indicator of failure: the
42 * first indicator is usually the fact the action the user expected to happen
43 * did not happen.
44 *
45 * Example: User fills a form, clicks "Submit".
46 *
47 * @li Expected feedback: form closes
48 * @li First indicator of failure: form stays there
49 * @li Second indicator of failure: a KMessageWidget appears on top of the
50 * form, explaining the error condition
51 *
52 * When used to provide negative feedback, KMessageWidget should be placed
53 * close to its context. In the case of a form, it should appear on top of the
54 * form entries.
55 *
56 * KMessageWidget should get inserted in the existing layout. Space should not
57 * be reserved for it, otherwise it becomes "dead space", ignored by the user.
58 * KMessageWidget should also not appear as an overlay to prevent blocking
59 * access to elements the user needs to interact with to fix the failure.
60 *
61 * <b>Positive feedback</b>
62 *
63 * KMessageWidget can be used for positive feedback but it shouldn't be
64 * overused. It is often enough to provide feedback by simply showing the
65 * results of an action.
66 *
67 * Examples of acceptable uses:
68 *
69 * @li Confirm success of "critical" transactions
70 * @li Indicate completion of background tasks
71 *
72 * Example of inadapted uses:
73 *
74 * @li Indicate successful saving of a file
75 * @li Indicate a file has been successfully removed
76 *
77 * <b>Opportunistic interaction</b>
78 *
79 * Opportunistic interaction is the situation where the application suggests to
80 * the user an action he could be interested in perform, either based on an
81 * action the user just triggered or an event which the application noticed.
82 *
83 * Example of acceptable uses:
84 *
85 * @li A browser can propose remembering a recently entered password
86 * @li A music collection can propose ripping a CD which just got inserted
87 * @li A chat application may notify the user a "special friend" just connected
88 *
89 * @author Aurélien Gâteau <agateau@kde.org>
90 * @since 4.7
91 */
92class KDEUI_EXPORT KMessageWidget : public QFrame
93{
94 Q_OBJECT
95 Q_ENUMS(MessageType)
96
97 Q_PROPERTY(QString text READ text WRITE setText)
98 Q_PROPERTY(bool wordWrap READ wordWrap WRITE setWordWrap)
99 Q_PROPERTY(bool closeButtonVisible READ isCloseButtonVisible WRITE setCloseButtonVisible)
100 Q_PROPERTY(MessageType messageType READ messageType WRITE setMessageType)
101 Q_PROPERTY(QIcon icon READ icon WRITE setIcon)
102public:
103 enum MessageType {
104 Positive,
105 Information,
106 Warning,
107 Error
108 };
109
110 /**
111 * Constructs a KMessageWidget with the specified parent.
112 */
113 explicit KMessageWidget(QWidget *parent = 0);
114
115 explicit KMessageWidget(const QString &text, QWidget *parent = 0);
116
117 ~KMessageWidget();
118
119 QString text() const;
120
121 bool wordWrap() const;
122
123 bool isCloseButtonVisible() const;
124
125 MessageType messageType() const;
126
127 void addAction(QAction *action);
128
129 void removeAction(QAction *action);
130
131 QSize sizeHint() const;
132
133 QSize minimumSizeHint() const;
134
135 int heightForWidth(int width) const;
136
137 /**
138 * The icon shown on the left of the text. By default, no icon is shown.
139 * @since 4.11
140 */
141 QIcon icon() const;
142
143public Q_SLOTS:
144 void setText(const QString &text);
145
146 void setWordWrap(bool wordWrap);
147
148 void setCloseButtonVisible(bool visible);
149
150 void setMessageType(KMessageWidget::MessageType type);
151
152 /**
153 * Show the widget using an animation, unless
154 * KGlobalSettings::graphicsEffectLevel() does not allow simple effects.
155 */
156 void animatedShow();
157
158 /**
159 * Hide the widget using an animation, unless
160 * KGlobalSettings::graphicsEffectLevel() does not allow simple effects.
161 */
162 void animatedHide();
163
164 /**
165 * Define an icon to be shown on the left of the text
166 * @since 4.11
167 */
168 void setIcon(const QIcon &icon);
169
170Q_SIGNALS:
171 /**
172 * This signal is emitted when the user clicks a link in the text label.
173 * The URL referred to by the href anchor is passed in contents.
174 * @param contents text of the href anchor
175 * @see QLabel::linkActivated()
176 * @since 4.10
177 */
178 void linkActivated(const QString& contents);
179
180 /**
181 * This signal is emitted when the user hovers over a link in the text label.
182 * The URL referred to by the href anchor is passed in contents.
183 * @param contents text of the href anchor
184 * @see QLabel::linkHovered()
185 * @since 4.11
186 */
187 void linkHovered(const QString& contents);
188
189protected:
190 void paintEvent(QPaintEvent *event);
191
192 bool event(QEvent *event);
193
194 void resizeEvent(QResizeEvent *event);
195
196 void showEvent(QShowEvent *event);
197
198private:
199 KMessageWidgetPrivate *const d;
200 friend class KMessageWidgetPrivate;
201
202 Q_PRIVATE_SLOT(d, void slotTimeLineChanged(qreal))
203 Q_PRIVATE_SLOT(d, void slotTimeLineFinished())
204};
205
206#endif /* KMESSAGEWIDGET_H */
207