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 | |
26 | class ; |
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 | */ |
45 | class KDEGAMES_EXPORT : public QObject, public QGraphicsItem |
46 | { |
47 | Q_OBJECT |
48 | Q_INTERFACES(QGraphicsItem) |
49 | public: |
50 | /** |
51 | * Possible values for message showing mode in respect to a previous |
52 | * message |
53 | */ |
54 | enum { , }; |
55 | /** |
56 | * Possible values for the popup angles sharpness |
57 | */ |
58 | enum { =0, =2, =5, =10 }; |
59 | /** |
60 | * The possible places in the scene where a message can be shown |
61 | */ |
62 | enum { , , , , }; |
63 | /** |
64 | * Constructs a message item. It is hidden by default. |
65 | */ |
66 | (QGraphicsItem * parent = 0); |
67 | /** |
68 | * Destructs a message item |
69 | */ |
70 | (); |
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 ( 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 ( int msec ); |
99 | /** |
100 | * @return timeout that is currently set |
101 | */ |
102 | int () 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 ( qreal opacity ); |
109 | /** |
110 | * @return current message opacity |
111 | */ |
112 | qreal () const; |
113 | /** |
114 | * Sets custom pixmap to show instead of default icon on the left |
115 | */ |
116 | void ( 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 ( bool hide ); |
122 | /** |
123 | * @return whether this popup item hides on mouse click. |
124 | */ |
125 | bool () const; |
126 | /** |
127 | * Used to specify how to hide in forceHide() - instantly or animatedly |
128 | */ |
129 | enum { , }; |
130 | /** |
131 | * Requests the item to be hidden immediately. |
132 | */ |
133 | void (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 ( 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 ( const QColor& color ); |
146 | /** |
147 | * @return the bounding rect of this item. Reimplemented from QGraphicsItem |
148 | */ |
149 | virtual QRectF () const; |
150 | /** |
151 | * Paints item. Reimplemented from QGraphicsItem |
152 | */ |
153 | virtual void ( QPainter* p, const QStyleOptionGraphicsItem *option, QWidget* widget ); |
154 | /** |
155 | * Sets the popup angles sharpness |
156 | */ |
157 | void ( Sharpness sharpness ); |
158 | /** |
159 | * @return current popup angles sharpness |
160 | */ |
161 | Sharpness () const; |
162 | Q_SIGNALS: |
163 | /** |
164 | * Emitted when user clicks on a link in item |
165 | */ |
166 | void ( const QString& link ); |
167 | /** |
168 | * Emitted when user hovers a link in item |
169 | */ |
170 | void ( 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 (); |
176 | private Q_SLOTS: |
177 | void (int); |
178 | void (); |
179 | void (); |
180 | void (const QString&); |
181 | void (); |
182 | private: |
183 | void (); |
184 | virtual void ( QGraphicsSceneMouseEvent* ); |
185 | virtual void ( QGraphicsSceneMouseEvent* ); |
186 | virtual void ( QGraphicsSceneHoverEvent* ); |
187 | virtual void ( QGraphicsSceneHoverEvent* ); |
188 | |
189 | KGamePopupItemPrivate * const ; |
190 | }; |
191 | |
192 | #endif |
193 | |