File indexing completed on 2024-05-19 12:54:44

 /* This file is part of the KDE libraries
  *
  * Copyright (c) 2011 Aurélien Gâteau <agateau@kde.org>
  * Copyright (C) 2011-2012 Jarosław Staniek <staniek@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 "kexiutils_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 they 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
  */
 class KEXIUTILS_EXPORT KMessageWidget : public QFrame
 {
     Q_OBJECT
 
     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)
 public:
     enum MessageType {
         Positive,
         Information,
         Warning,
         Error
     };
     Q_ENUM(MessageType)
 
     enum CalloutPointerDirection {
         NoPointer,
         Up,
         Down,
         Left,
         Right
     };
     Q_ENUM(CalloutPointerDirection)
 
     /**
      * Constructs a KMessageWidget with the specified parent.
      */
     explicit KMessageWidget(QWidget *parent = 0);
 
     explicit KMessageWidget(const QString &text, QWidget *parent = 0);
 
     KMessageWidget(QWidget *contentsWidget, QWidget *parent);
 
     ~KMessageWidget();
 
     QString text() const;
 
     bool wordWrap() const;
 
     bool isCloseButtonVisible() const;
 
     bool clickClosesMessage() const;
 
     MessageType messageType() const;
 
     CalloutPointerDirection calloutPointerDirection() const;
 
     void addAction(QAction *action);
 
     void removeAction(QAction *action);
 
     void setDefaultAction(QAction *action);
 
     void setButtonLeftAlignedForAction(QAction *action);
 
     /**
      * @brief Sets autodeletion flag to be on or off.
      * If autodeletion is on, the widget is automatically
      * deleted after hide() or animatedHide() using QObject::deleteLater().
      * Autodeletion is false by default.
      */
     void setAutoDelete(bool set);
 
     QSize sizeHint() const override;
 
     QSize minimumSizeHint() const override;
 
     QPoint calloutPointerPosition() const;
 
 public Q_SLOTS:
     void setText(const QString &text);
 
     void setWordWrap(bool wordWrap);
 
     void setCloseButtonVisible(bool visible);
 
     void setClickClosesMessage(bool set);
 
     void setMessageType(KMessageWidget::MessageType type);
 
     void setCalloutPointerDirection(KMessageWidget::CalloutPointerDirection direction);
 
     //! Sets global position for callout pointer
     void setCalloutPointerPosition(const QPoint& globalPos);
 
     QBrush backgroundBrush() const;
 
     QBrush borderBrush() const;
 
     /**
      * Show the widget using an animation, unless
      * KexiUtils::graphicsEffectLevel() does not allow simple effects.
      */
     void animatedShow();
 
     /**
      * Hide the widget using an animation, unless
      * KexiUtils::graphicsEffectLevel() does not allow simple effects.
      */
     void animatedHide();
 
     void resizeToContents();
 
 Q_SIGNALS:
     void animatedShowFinished();
     void animatedHideFinished();
 
 protected:
     virtual void paintEvent(QPaintEvent *event) override;
 
     virtual bool event(QEvent *event) override;
 
     virtual void resizeEvent(QResizeEvent *event) override;
 
     virtual void showEvent(QShowEvent *event) override;
 
 private Q_SLOTS:
     void slotTimeLineChanged(qreal value);
     void slotTimeLineFinished();
     void tryClickCloseMessage();
 
 private:
     KMessageWidgetPrivate *const d;
     friend class KMessageWidgetPrivate;
 };
 
 #endif /* KMESSAGEWIDGET_H */