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
27class QGraphicsProxyWidget;
28class QGraphicsLinearLayout;
29
30namespace Plasma
31{
32
33class Dialog;
34class IconWidget;
35class PopupAppletPrivate;
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
52class PLASMA_EXPORT PopupApplet : public Plasma::Applet
53{
54 Q_OBJECT
55 Q_PROPERTY(Qt::AlignmentFlag popupAlignment READ popupAlignment WRITE setPopupAlignment)
56
57public:
58 PopupApplet(QObject *parent, const QVariantList &args);
59 ~PopupApplet();
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 setPopupIcon(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 setPopupIcon(const QString &iconName);
79
80 /**
81 * @return the icon that is displayed when the applet is in a panel.
82 */
83 QIcon popupIcon() 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 *widget();
91 void setWidget(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 *graphicsWidget();
101 void setGraphicsWidget(QGraphicsWidget * widget);
102
103 /**
104 * @return the placement of the popup relating to the applet
105 */
106 Plasma::PopupPlacement 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 setPopupAlignment(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 popupAlignment() 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 setPassivePopup(bool passive);
128
129 /**
130 * @return true if the dialog will be treated as a passive poup
131 */
132 bool isPassivePopup() const;
133
134 /**
135 * @return true if the applet is popped up
136 */
137 bool isPopupShowing() const;
138
139 /**
140 * @return true if the applet is collapsed to an icon
141 * @since 4.6
142 */
143 bool isIconified() const;
144
145
146public Q_SLOTS:
147 /**
148 * Hides the popup.
149 */
150 void hidePopup();
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 showPopup(uint displayTime = 0);
158
159 /**
160 * Toggles the popup.
161 */
162 void togglePopup();
163
164protected:
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 popupEvent(bool show);
173
174 /**
175 * Reimplemented from QGraphicsLayoutItem
176 */
177 QSizeF sizeHint(Qt::SizeHint which, const QSizeF & constraint = QSizeF()) const;
178
179 /**
180 * Reimplemented from QGraphicsLayoutItem
181 */
182 void mousePressEvent(QGraphicsSceneMouseEvent *event);
183
184 /**
185 * Reimplemented from QGraphicsLayoutItem
186 */
187 void mouseReleaseEvent(QGraphicsSceneMouseEvent *event);
188
189 /**
190 * Reimplemented from QGraphicsLayoutItem
191 */
192 bool eventFilter(QObject *watched, QEvent *event);
193
194 /**
195 * Reimplemented from QGraphicsLayoutItem
196 */
197 void dragEnterEvent(QGraphicsSceneDragDropEvent *event);
198
199 /**
200 * Reimplemented from QGraphicsLayoutItem
201 */
202 void dragLeaveEvent(QGraphicsSceneDragDropEvent *event);
203
204 /**
205 * Reimplemented from QGraphicsLayoutItem
206 */
207 void dropEvent(QGraphicsSceneDragDropEvent *event);
208
209 /**
210 * Reimplemented from QGraphicsLayoutItem
211 */
212 void timerEvent(QTimerEvent *event);
213
214private:
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 PopupApplet(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 d;
240};
241
242} // Plasma namespace
243
244#endif /* POPUPAPPLET_H */
245
246