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