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 */
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;
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();
169private Q_SLOTS:
170 void animationFrame(int);
171 void hideMe();
172 void playHideAnimation();
173 void onLinkHovered(const QString &);
174 void onTextItemClicked();
175
176private:
177 void setupTimeline();
182
183private:
184 std::unique_ptr<KGamePopupItemPrivate> const d_ptr;
186};
187
188#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
T qobject_cast(QObject *object)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:16:50 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.