diff options
Diffstat (limited to 'qt-ui/kmessagewidget.h')
| -rw-r--r-- | qt-ui/kmessagewidget.h | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/qt-ui/kmessagewidget.h b/qt-ui/kmessagewidget.h new file mode 100644 index 000000000..e35676a59 --- /dev/null +++ b/qt-ui/kmessagewidget.h @@ -0,0 +1,241 @@ +/* This file is part of the KDE libraries + * + * Copyright (c) 2011 Aurélien Gâteau <agateau@kde.org> + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + * 02110-1301 USA + */ +#ifndef KMESSAGEWIDGET_H +#define KMESSAGEWIDGET_H + +#include <kdeui_export.h> + +#include <QFrame> + +class KMessageWidgetPrivate; + +/** + * @short A widget to provide feedback or propose opportunistic interactions. + * + * KMessageWidget can be used to provide inline positive or negative + * feedback, or to implement opportunistic interactions. + * + * As a feedback widget, KMessageWidget provides a less intrusive alternative + * to "OK Only" message boxes. If you do not need the modalness of KMessageBox, + * consider using KMessageWidget instead. + * + * <b>Negative feedback</b> + * + * The KMessageWidget can be used as a secondary indicator of failure: the + * first indicator is usually the fact the action the user expected to happen + * did not happen. + * + * Example: User fills a form, clicks "Submit". + * + * @li Expected feedback: form closes + * @li First indicator of failure: form stays there + * @li Second indicator of failure: a KMessageWidget appears on top of the + * form, explaining the error condition + * + * When used to provide negative feedback, KMessageWidget should be placed + * close to its context. In the case of a form, it should appear on top of the + * form entries. + * + * KMessageWidget should get inserted in the existing layout. Space should not + * be reserved for it, otherwise it becomes "dead space", ignored by the user. + * KMessageWidget should also not appear as an overlay to prevent blocking + * access to elements the user needs to interact with to fix the failure. + * + * <b>Positive feedback</b> + * + * KMessageWidget can be used for positive feedback but it shouldn't be + * overused. It is often enough to provide feedback by simply showing the + * results of an action. + * + * Examples of acceptable uses: + * + * @li Confirm success of "critical" transactions + * @li Indicate completion of background tasks + * + * Example of inadapted uses: + * + * @li Indicate successful saving of a file + * @li Indicate a file has been successfully removed + * + * <b>Opportunistic interaction</b> + * + * Opportunistic interaction is the situation where the application suggests to + * the user an action he could be interested in perform, either based on an + * action the user just triggered or an event which the application noticed. + * + * Example of acceptable uses: + * + * @li A browser can propose remembering a recently entered password + * @li A music collection can propose ripping a CD which just got inserted + * @li A chat application may notify the user a "special friend" just connected + * + * @author Aurélien Gâteau <agateau@kde.org> + * @since 4.7 + */ +class KMessageWidget : public QFrame +{ + Q_OBJECT + Q_ENUMS(MessageType) + + Q_PROPERTY(QString text READ text WRITE setText) + Q_PROPERTY(bool wordWrap READ wordWrap WRITE setWordWrap) + Q_PROPERTY(bool closeButtonVisible READ isCloseButtonVisible WRITE setCloseButtonVisible) + Q_PROPERTY(MessageType messageType READ messageType WRITE setMessageType) + Q_PROPERTY(QIcon icon READ icon WRITE setIcon) +public: + enum MessageType { + Positive, + Information, + Warning, + Error + }; + + /** + * Constructs a KMessageWidget with the specified parent. + */ + explicit KMessageWidget(QWidget *parent = 0); + + explicit KMessageWidget(const QString &text, QWidget *parent = 0); + + ~KMessageWidget(); + + QString text() const; + + bool wordWrap() const; + + bool isCloseButtonVisible() const; + + MessageType messageType() const; + + void addAction(QAction *action); + + void removeAction(QAction *action); + + QSize sizeHint() const; + + QSize minimumSizeHint() const; + + int heightForWidth(int width) const; + + /** + * The icon shown on the left of the text. By default, no icon is shown. + * @since 4.11 + */ + QIcon icon() const; + +public Q_SLOTS: + void setText(const QString &text); + + void setWordWrap(bool wordWrap); + + void setCloseButtonVisible(bool visible); + + void setMessageType(KMessageWidget::MessageType type); + + /** + * Show the widget using an animation, unless + * KGlobalSettings::graphicsEffectLevel() does not allow simple effects. + */ + void animatedShow(); + + /** + * Hide the widget using an animation, unless + * KGlobalSettings::graphicsEffectLevel() does not allow simple effects. + */ + void animatedHide(); + + /** + * Define an icon to be shown on the left of the text + * @since 4.11 + */ + void setIcon(const QIcon &icon); + +Q_SIGNALS: + /** + * This signal is emitted when the user clicks a link in the text label. + * The URL referred to by the href anchor is passed in contents. + * @param contents text of the href anchor + * @see QLabel::linkActivated() + * @since 4.10 + */ + void linkActivated(const QString& contents); + + /** + * This signal is emitted when the user hovers over a link in the text label. + * The URL referred to by the href anchor is passed in contents. + * @param contents text of the href anchor + * @see QLabel::linkHovered() + * @since 4.11 + */ + void linkHovered(const QString& contents); + +protected: + void paintEvent(QPaintEvent *event); + + bool event(QEvent *event); + + void resizeEvent(QResizeEvent *event); + + void showEvent(QShowEvent *event); + +private: + KMessageWidgetPrivate *const d; + friend class KMessageWidgetPrivate; + + Q_PRIVATE_SLOT(d, void slotTimeLineChanged(qreal)) + Q_PRIVATE_SLOT(d, void slotTimeLineFinished()) +}; + +//--------------------------------------------------------------------- +// KMessageWidgetPrivate +//--------------------------------------------------------------------- +class QLabel; +class QToolButton; +class QTimeLine; +#include <QIcon> + +class KMessageWidgetPrivate +{ +public: + void init(KMessageWidget*); + + KMessageWidget* q; + QFrame* content; + QLabel* iconLabel; + QLabel* textLabel; + QToolButton* closeButton; + QTimeLine* timeLine; + QIcon icon; + + KMessageWidget::MessageType messageType; + bool wordWrap; + QList<QToolButton*> buttons; + QPixmap contentSnapShot; + + void createLayout(); + void updateSnapShot(); + void updateLayout(); + void slotTimeLineChanged(qreal); + void slotTimeLineFinished(); + + int bestContentHeight() const; +}; + +#endif /* KMESSAGEWIDGET_H */ |