KDEGames

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

KDE's Doxygen guidelines are available online.