1 | /* |
2 | * Copyright 2008 by Montel Laurent <montel@kde.org> |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Lesser General Public |
6 | * License as published by the Free Software Foundation; either |
7 | * version 2.1 of the License, or (at your option) any later version. |
8 | * |
9 | * This library 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 GNU |
12 | * Lesser General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Lesser General Public |
15 | * License along with this library; if not, write to the Free Software |
16 | * Foundation, Inc., 51 Franklin St, Fifth Floor, |
17 | * Boston, MA 02110-1301 USA |
18 | */ |
19 | |
20 | #ifndef PLASMA_POPUPAPPLET_H |
21 | #define PLASMA_POPUPAPPLET_H |
22 | |
23 | #include <plasma/applet.h> |
24 | #include <plasma/plasma_export.h> |
25 | #include <plasma/plasma.h> |
26 | |
27 | class QGraphicsProxyWidget; |
28 | class QGraphicsLinearLayout; |
29 | |
30 | namespace Plasma |
31 | { |
32 | |
33 | class Dialog; |
34 | class IconWidget; |
35 | class ; |
36 | |
37 | /** |
38 | * Allows applets to automatically 'collapse' into an icon when put in an panel, and is a convenient |
39 | * base class for any applet that wishes to use extenders. |
40 | * |
41 | * Applets that subclass this class should implement either widget() or graphicsWidget() to return a |
42 | * widget that will be displayed in the applet if the applet is in a Planar or MediaCenter form |
43 | * factor. If the applet is put in a panel, an icon will be displayed instead, which shows the |
44 | * widget in a popup when clicked. |
45 | * |
46 | * If you use this class as a base class for your extender using applet, the extender will |
47 | * automatically be used for the popup; reimplementing graphicsWidget() is unnecessary in this case. |
48 | * If you need a popup that does not steal window focus when openend or used, set window flag |
49 | * Qt::X11BypassWindowManagerHint the widget returned by widget() or graphicsWidget(). |
50 | */ |
51 | |
52 | class PLASMA_EXPORT : public Plasma::Applet |
53 | { |
54 | Q_OBJECT |
55 | Q_PROPERTY(Qt::AlignmentFlag popupAlignment READ popupAlignment WRITE setPopupAlignment) |
56 | |
57 | public: |
58 | (QObject *parent, const QVariantList &args); |
59 | (); |
60 | |
61 | /** |
62 | * @param icon the icon that has to be displayed when the applet is in a panel. |
63 | * Passing in a null icon means that the popup applet itself |
64 | * will provide an interface for when the PopupApplet is not showing |
65 | * the widget() or graphicsWidget() directly. |
66 | */ |
67 | void (const QIcon &icon); |
68 | |
69 | /** |
70 | * @param icon the icon that has to be displayed when the applet is in a panel. |
71 | * Passing in an empty QString() means that the popup applet itself |
72 | * will provide an interface for when the PopupApplet is not showing |
73 | * the widget() or graphicsWidget() directly. |
74 | |
75 | * If you set a popup icon you must also set a minimum size of the applet. When the applet |
76 | * is smaller than this minimum size, it will be displayed as that icon. |
77 | */ |
78 | void (const QString &iconName); |
79 | |
80 | /** |
81 | * @return the icon that is displayed when the applet is in a panel. |
82 | */ |
83 | QIcon () const; |
84 | |
85 | /** |
86 | * Implement either this function or graphicsWidget(). |
87 | * @return the widget that will get shown in either a layout, in the applet or in a Dialog, |
88 | * depending on the form factor of the applet. |
89 | */ |
90 | virtual QWidget *(); |
91 | void (QWidget * widget); |
92 | |
93 | /** |
94 | * Implement either this function or widget(). |
95 | * @return the widget that will get shown in either a layout, in the applet or in a Dialog, |
96 | * depending on the form factor of the applet. |
97 | * If you set a popup icon you must also set a minimum size of the applet. When the applet |
98 | * is smaller than this minimum size, it will be displayed as that icon. |
99 | */ |
100 | virtual QGraphicsWidget *(); |
101 | void (QGraphicsWidget * widget); |
102 | |
103 | /** |
104 | * @return the placement of the popup relating to the applet |
105 | */ |
106 | Plasma::PopupPlacement () const; |
107 | |
108 | /** |
109 | * Sets the default alignment of the popup relative to the applet |
110 | * @param alignment the alignment to use; Qt::AlignLeft or Qt::AlignRight |
111 | * @since 4.6 |
112 | */ |
113 | void (Qt::AlignmentFlag alignment); |
114 | |
115 | /** |
116 | * @return the default alignment of the popup relative to the applet |
117 | * @since 4.6 |
118 | */ |
119 | Qt::AlignmentFlag () const; |
120 | |
121 | /** |
122 | * Sets whether or not the dialog popup that gets created should be a "passive" popup |
123 | * that does not steal focus from other windows or not. |
124 | * |
125 | * @param passive true if the dialog should be treated as a passive popup |
126 | */ |
127 | void (bool passive); |
128 | |
129 | /** |
130 | * @return true if the dialog will be treated as a passive poup |
131 | */ |
132 | bool () const; |
133 | |
134 | /** |
135 | * @return true if the applet is popped up |
136 | */ |
137 | bool () const; |
138 | |
139 | /** |
140 | * @return true if the applet is collapsed to an icon |
141 | * @since 4.6 |
142 | */ |
143 | bool () const; |
144 | |
145 | |
146 | public Q_SLOTS: |
147 | /** |
148 | * Hides the popup. |
149 | */ |
150 | void (); |
151 | |
152 | /** |
153 | * Shows the dialog showing the widget if the applet is in a panel. |
154 | * @param displayTime the time in ms that the popup should be displayed, defaults to 0 which means |
155 | * always (until the user closes it again, that is). |
156 | */ |
157 | void (uint displayTime = 0); |
158 | |
159 | /** |
160 | * Toggles the popup. |
161 | */ |
162 | void (); |
163 | |
164 | protected: |
165 | /** |
166 | * This event handler can be reimplemented in a subclass to receive an |
167 | * event before the popup is shown or hidden. |
168 | * @param show true if the popup is going to be shown, false if the popup |
169 | * is going to be hidden. |
170 | * Note that showing and hiding the popup on click is already done in PopupApplet. |
171 | */ |
172 | virtual void (bool show); |
173 | |
174 | /** |
175 | * Reimplemented from QGraphicsLayoutItem |
176 | */ |
177 | QSizeF (Qt::SizeHint which, const QSizeF & constraint = QSizeF()) const; |
178 | |
179 | /** |
180 | * Reimplemented from QGraphicsLayoutItem |
181 | */ |
182 | void (QGraphicsSceneMouseEvent *event); |
183 | |
184 | /** |
185 | * Reimplemented from QGraphicsLayoutItem |
186 | */ |
187 | void (QGraphicsSceneMouseEvent *event); |
188 | |
189 | /** |
190 | * Reimplemented from QGraphicsLayoutItem |
191 | */ |
192 | bool (QObject *watched, QEvent *event); |
193 | |
194 | /** |
195 | * Reimplemented from QGraphicsLayoutItem |
196 | */ |
197 | void (QGraphicsSceneDragDropEvent *event); |
198 | |
199 | /** |
200 | * Reimplemented from QGraphicsLayoutItem |
201 | */ |
202 | void (QGraphicsSceneDragDropEvent *event); |
203 | |
204 | /** |
205 | * Reimplemented from QGraphicsLayoutItem |
206 | */ |
207 | void (QGraphicsSceneDragDropEvent *event); |
208 | |
209 | /** |
210 | * Reimplemented from QGraphicsLayoutItem |
211 | */ |
212 | void (QTimerEvent *event); |
213 | |
214 | private: |
215 | /** |
216 | * @internal This constructor is to be used with the Package loading system. |
217 | * |
218 | * @param parent a QObject parent; you probably want to pass in 0 |
219 | * @param args a list of strings containing two entries: the service id |
220 | * and the applet id |
221 | * @since 4.3 |
222 | */ |
223 | (const QString &packagePath, uint appletId, const QVariantList &args); |
224 | |
225 | Q_PRIVATE_SLOT(d, void internalTogglePopup()) |
226 | Q_PRIVATE_SLOT(d, void hideTimedPopup()) |
227 | Q_PRIVATE_SLOT(d, void clearPopupLostFocus()) |
228 | Q_PRIVATE_SLOT(d, void dialogSizeChanged()) |
229 | Q_PRIVATE_SLOT(d, void dialogStatusChanged(bool)) |
230 | Q_PRIVATE_SLOT(d, void updateDialogPosition()) |
231 | Q_PRIVATE_SLOT(d, void appletActivated()) |
232 | Q_PRIVATE_SLOT(d, void iconSizeChanged(int)) |
233 | Q_PRIVATE_SLOT(d, void statusChangeWhileShown(Plasma::ItemStatus status)) |
234 | |
235 | friend class Applet; |
236 | friend class AppletPrivate; |
237 | friend class Extender; |
238 | friend class PopupAppletPrivate; |
239 | PopupAppletPrivate * const ; |
240 | }; |
241 | |
242 | } // Plasma namespace |
243 | |
244 | #endif /* POPUPAPPLET_H */ |
245 | |
246 | |