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

KDE's Doxygen guidelines are available online.