File indexing completed on 2024-04-28 04:05:03

 /*
     SPDX-FileCopyrightText: 2007 Dmitry Suzdalev <dimsuz@gmail.com>
 
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #ifndef K_GAME_POPUP_ITEM_H
 #define K_GAME_POPUP_ITEM_H
 
 // own
 #include "kdegames_export.h"
 // Qt
 #include <QGraphicsItem>
 #include <QObject>
 // Std
 #include <memory>
 
 class KGamePopupItemPrivate;
 
 /**
  * \class KGamePopupItem kgamepopupitem.h <KGamePopupItem>
  *
  * QGraphicsItem capable of showing short popup messages
  * which do not interrupt the gameplay.
  * Message can stay on screen for specified amount of time
  * and automatically hide after (unless user hovers it with mouse).
  *
  * Example of use:
  * \code
  * KGamePopupItem *messageItem = new KGamePopupItem();
  * myGraphicsScene->addItem(messageItem);
  * ...
  * messageItem->setMessageTimeout( 3000 ); // 3 sec
  * messageItem->showMessage("Hello, I'm a game message! How do you do?", BottomLeft);
  * \endcode
  */
 class KDEGAMES_EXPORT KGamePopupItem : public QObject, public QGraphicsItem
 {
     Q_OBJECT
     Q_INTERFACES(QGraphicsItem)
 
 public:
     /**
      * Possible values for message showing mode in respect to a previous
      * message
      */
     enum ReplaceMode { LeavePrevious, ReplacePrevious };
     /**
      * Possible values for the popup angles sharpness
      */
     enum Sharpness { Square = 0, Sharp = 2, Soft = 5, Softest = 10 };
     /**
      * The possible places in the scene where a message can be shown
      */
     enum Position { TopLeft, TopRight, BottomLeft, BottomRight, Center };
     /**
      * Constructs a message item. It is hidden by default.
      */
     explicit KGamePopupItem(QGraphicsItem *parent = nullptr);
     /**
      * Destructs a message item
      */
     ~KGamePopupItem() override;
     /**
      * Shows the message: item will appear at specified place
      * of the scene using simple animation
      * Item will be automatically hidden after timeout set in setMessageTimeOut() passes
      * If item is hovered with mouse it won't hide until user moves
      * the mouse away
      *
      * Note that if pos == Center, message animation will be of fade in/out type,
      * rather than slide in/out
      *
      * @param text holds the message to show
      * @param pos position on the scene where the message will appear
      * @param mode how to handle an already shown message by this item:
        either leave it and ignore the new one or replace it
      */
     void showMessage(const QString &text, Position pos, ReplaceMode mode = LeavePrevious);
     /**
      * Sets the amount of time the item will stay visible on screen
      * before it goes away.
      * By default item is shown for 2000 msec
      * If item is hovered with mouse it will hide only after
      * user moves the mouse away
      *
      * @param msec amount of time in milliseconds.
      * if msec is 0, then message will stay visible until it
      * gets explicitly hidden by forceHide()
      */
     void setMessageTimeout(int msec);
     /**
      * @return timeout that is currently set
      */
     int messageTimeout() const;
     /**
      * Sets the message opacity from 0 (fully transparent) to 1 (fully opaque)
      * For example 0.5 is half transparent
      * It defaults to 1.0
      */
     void setMessageOpacity(qreal opacity);
     /**
      * @return current message opacity
      */
     qreal messageOpacity() const;
     /**
      * Sets custom pixmap to show instead of default icon on the left
      */
     void setMessageIcon(const QPixmap &pix);
     /**
      * Sets whether to hide this popup item on mouse click.
      * By default a mouse click will cause an item to hide
      */
     void setHideOnMouseClick(bool hide);
     /**
      * @return whether this popup item hides on mouse click.
      */
     bool hidesOnMouseClick() const;
     /**
      * Used to specify how to hide in forceHide() - instantly or animatedly
      */
     enum HideType { InstantHide, AnimatedHide };
     /**
      * Requests the item to be hidden immediately.
      */
     void forceHide(HideType type = AnimatedHide);
     /**
      * Sets brush used to paint item background
      * By default system-default brush is used
      * @see KColorScheme
      */
     void setBackgroundBrush(const QBrush &brush);
     /**
      * Sets default color for unformatted text
      * By default system-default color is used
      * @see KColorScheme
      */
     void setTextColor(const QColor &color);
     /**
      * @return the bounding rect of this item. Reimplemented from QGraphicsItem
      */
     QRectF boundingRect() const override;
     /**
      * Paints item. Reimplemented from QGraphicsItem
      */
     void paint(QPainter *p, const QStyleOptionGraphicsItem *option, QWidget *widget) override;
     /**
      * Sets the popup angles sharpness
      */
     void setSharpness(Sharpness sharpness);
     /**
      * @return current popup angles sharpness
      */
     Sharpness sharpness() const;
 Q_SIGNALS:
     /**
      * Emitted when user clicks on a link in item
      */
     void linkActivated(const QString &link);
     /**
      * Emitted when user hovers a link in item
      */
     void linkHovered(const QString &link);
     /**
      * Emitted when the popup finishes hiding. This includes hiding caused by
      * both timeouts and mouse clicks.
      */
     void hidden();
 private Q_SLOTS:
     void animationFrame(int);
     void hideMe();
     void playHideAnimation();
     void onLinkHovered(const QString &);
     void onTextItemClicked();
 
 private:
     void setupTimeline();
     void mousePressEvent(QGraphicsSceneMouseEvent *) override;
     void mouseReleaseEvent(QGraphicsSceneMouseEvent *) override;
     void hoverEnterEvent(QGraphicsSceneHoverEvent *) override;
     void hoverLeaveEvent(QGraphicsSceneHoverEvent *) override;
 
 private:
     std::unique_ptr<KGamePopupItemPrivate> const d_ptr;
     Q_DECLARE_PRIVATE(KGamePopupItem)
 };
 
 #endif