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 | |
27 | class 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 | */ |
92 | class 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) |
102 | public: |
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 | |
143 | public 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 | |
170 | Q_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 | |
189 | protected: |
190 | void paintEvent(QPaintEvent *event); |
191 | |
192 | bool event(QEvent *event); |
193 | |
194 | void resizeEvent(QResizeEvent *event); |
195 | |
196 | void showEvent(QShowEvent *event); |
197 | |
198 | private: |
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 | |