1
/* This file is part of the KDE libraries
3
* Copyright (c) 2011 Aurélien Gâteau <agateau@kde.org>
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.
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.
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
20
#ifndef KMESSAGEWIDGET_H
21
#define KMESSAGEWIDGET_H
23
#include <kdeui_export.h>
27
class KMessageWidgetPrivate;
30
* @short A widget to provide feedback or propose opportunistic interactions.
32
* KMessageWidget can be used to provide inline positive or negative
33
* feedback, or to implement opportunistic interactions.
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.
39
* <b>Negative feedback</b>
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
45
* Example: User fills a form, clicks "Submit".
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
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
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.
61
* <b>Positive feedback</b>
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.
67
* Examples of acceptable uses:
69
* @li Confirm success of "critical" transactions
70
* @li Indicate completion of background tasks
72
* Example of inadapted uses:
74
* @li Indicate successful saving of a file
75
* @li Indicate a file has been successfully removed
77
* <b>Opportunistic interaction</b>
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.
83
* Example of acceptable uses:
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
89
* @author Aurélien Gâteau <agateau@kde.org>
92
class KDEUI_EXPORT KMessageWidget : public QFrame
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)
110
* Constructs a KMessageWidget with the specified parent.
112
explicit KMessageWidget(QWidget *parent = 0);
114
explicit KMessageWidget(const QString &text, QWidget *parent = 0);
118
QString text() const;
120
bool wordWrap() const;
122
bool isCloseButtonVisible() const;
124
MessageType messageType() const;
126
void addAction(QAction *action);
128
void removeAction(QAction *action);
130
QSize sizeHint() const;
132
QSize minimumSizeHint() const;
135
void setText(const QString &text);
137
void setWordWrap(bool wordWrap);
139
void setCloseButtonVisible(bool visible);
141
void setMessageType(KMessageWidget::MessageType type);
144
* Show the widget using an animation, unless
145
* KGlobalSettings::graphicsEffectLevel() does not allow simple effects.
150
* Hide the widget using an animation, unless
151
* KGlobalSettings::graphicsEffectLevel() does not allow simple effects.
156
void paintEvent(QPaintEvent *event);
158
bool event(QEvent *event);
160
void resizeEvent(QResizeEvent *event);
162
void showEvent(QShowEvent *event);
165
KMessageWidgetPrivate *const d;
166
friend class KMessageWidgetPrivate;
168
Q_PRIVATE_SLOT(d, void slotTimeLineChanged(qreal))
169
Q_PRIVATE_SLOT(d, void slotTimeLineFinished())
172
#endif /* KMESSAGEWIDGET_H */
added
removed
installer/backports/kmessagewidget.h
