KDEGames

kgamepopupitem.h
1 /*
2  SPDX-FileCopyrightText: 2007 Dmitry Suzdalev <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #ifndef K_GAME_POPUP_ITEM_H
8 #define K_GAME_POPUP_ITEM_H
9 
10 // own
11 #include <libkdegames_export.h>
12 // Qt
13 #include <QGraphicsItem>
14 #include <QObject>
15 // Std
16 #include <memory>
17 
18 class KGamePopupItemPrivate;
19 
20 /**
21  * \class KGamePopupItem kgamepopupitem.h <KGamePopupItem>
22  *
23  * QGraphicsItem capable of showing short popup messages
24  * which do not interrupt the gameplay.
25  * Message can stay on screen for specified amount of time
26  * and automatically hide after (unless user hovers it with mouse).
27  *
28  * Example of use:
29  * \code
30  * KGamePopupItem *messageItem = new KGamePopupItem();
31  * myGraphicsScene->addItem(messageItem);
32  * ...
33  * messageItem->setMessageTimeout( 3000 ); // 3 sec
34  * messageItem->showMessage("Hello, I'm a game message! How do you do?", BottomLeft);
35  * \endcode
36  */
37 class KDEGAMES_EXPORT KGamePopupItem : public QObject, public QGraphicsItem
38 {
39  Q_OBJECT
41 
42 public:
43  /**
44  * Possible values for message showing mode in respect to a previous
45  * message
46  */
47  enum ReplaceMode { LeavePrevious, ReplacePrevious };
48  /**
49  * Possible values for the popup angles sharpness
50  */
51  enum Sharpness { Square = 0, Sharp = 2, Soft = 5, Softest = 10 };
52  /**
53  * The possible places in the scene where a message can be shown
54  */
55  enum Position { TopLeft, TopRight, BottomLeft, BottomRight, Center };
56  /**
57  * Constructs a message item. It is hidden by default.
58  */
59  explicit KGamePopupItem(QGraphicsItem *parent = nullptr);
60  /**
61  * Destructs a message item
62  */
63  ~KGamePopupItem() override;
64  /**
65  * Shows the message: item will appear at specified place
66  * of the scene using simple animation
67  * Item will be automatically hidden after timeout set in setMessageTimeOut() passes
68  * If item is hovered with mouse it won't hide until user moves
69  * the mouse away
70  *
71  * Note that if pos == Center, message animation will be of fade in/out type,
72  * rather than slide in/out
73  *
74  * @param text holds the message to show
75  * @param pos position on the scene where the message will appear
76  * @param mode how to handle an already shown message by this item:
77  either leave it and ignore the new one or replace it
78  */
79  void showMessage(const QString &text, Position pos, ReplaceMode mode = LeavePrevious);
80  /**
81  * Sets the amount of time the item will stay visible on screen
82  * before it goes away.
83  * By default item is shown for 2000 msec
84  * If item is hovered with mouse it will hide only after
85  * user moves the mouse away
86  *
87  * @param msec amount of time in milliseconds.
88  * if msec is 0, then message will stay visible until it
89  * gets explicitly hidden by forceHide()
90  */
91  void setMessageTimeout(int msec);
92  /**
93  * @return timeout that is currently set
94  */
95  int messageTimeout() const;
96  /**
97  * Sets the message opacity from 0 (fully transparent) to 1 (fully opaque)
98  * For example 0.5 is half transparent
99  * It defaults to 1.0
100  */
101  void setMessageOpacity(qreal opacity);
102  /**
103  * @return current message opacity
104  */
105  qreal messageOpacity() const;
106  /**
107  * Sets custom pixmap to show instead of default icon on the left
108  */
109  void setMessageIcon(const QPixmap &pix);
110  /**
111  * Sets whether to hide this popup item on mouse click.
112  * By default a mouse click will cause an item to hide
113  */
114  void setHideOnMouseClick(bool hide);
115  /**
116  * @return whether this popup item hides on mouse click.
117  */
118  bool hidesOnMouseClick() const;
119  /**
120  * Used to specify how to hide in forceHide() - instantly or animatedly
121  */
122  enum HideType { InstantHide, AnimatedHide };
123  /**
124  * Requests the item to be hidden immediately.
125  */
126  void forceHide(HideType type = AnimatedHide);
127  /**
128  * Sets brush used to paint item background
129  * By default system-default brush is used
130  * @see KColorScheme
131  */
132  void setBackgroundBrush(const QBrush &brush);
133  /**
134  * Sets default color for unformatted text
135  * By default system-default color is used
136  * @see KColorScheme
137  */
138  void setTextColor(const QColor &color);
139  /**
140  * @return the bounding rect of this item. Reimplemented from QGraphicsItem
141  */
142  QRectF boundingRect() const override;
143  /**
144  * Paints item. Reimplemented from QGraphicsItem
145  */
146  void paint(QPainter *p, const QStyleOptionGraphicsItem *option, QWidget *widget) override;
147  /**
148  * Sets the popup angles sharpness
149  */
150  void setSharpness(Sharpness sharpness);
151  /**
152  * @return current popup angles sharpness
153  */
154  Sharpness sharpness() const;
155 Q_SIGNALS:
156  /**
157  * Emitted when user clicks on a link in item
158  */
159  void linkActivated(const QString &link);
160  /**
161  * Emitted when user hovers a link in item
162  */
163  void linkHovered(const QString &link);
164  /**
165  * Emitted when the popup finishes hiding. This includes hiding caused by
166  * both timeouts and mouse clicks.
167  */
168  void hidden();
169 private Q_SLOTS:
170  void animationFrame(int);
171  void hideMe();
172  void playHideAnimation();
173  void onLinkHovered(const QString &);
174  void onTextItemClicked();
175 
176 private:
177  void setupTimeline();
178  void mousePressEvent(QGraphicsSceneMouseEvent *) override;
180  void hoverEnterEvent(QGraphicsSceneHoverEvent *) override;
181  void hoverLeaveEvent(QGraphicsSceneHoverEvent *) override;
182 
183 private:
184  std::unique_ptr<KGamePopupItemPrivate> const d;
185 };
186 
187 #endif
HideType
Used to specify how to hide in forceHide() - instantly or animatedly.
virtual void hoverLeaveEvent(QGraphicsSceneHoverEvent *event)
Q_SLOTSQ_SLOTS
ReplaceMode
Possible values for message showing mode in respect to a previous message.
virtual QRectF boundingRect() const const=0
virtual void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget)=0
virtual void mousePressEvent(QGraphicsSceneMouseEvent *event)
Position
The possible places in the scene where a message can be shown.
Q_SIGNALSQ_SIGNALS
Q_INTERFACES(...)
Sharpness
Possible values for the popup angles sharpness.
virtual void mouseReleaseEvent(QGraphicsSceneMouseEvent *event)
virtual void hoverEnterEvent(QGraphicsSceneHoverEvent *event)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Jan 28 2023 03:56:45 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.