1 | /* |
2 | * Copyright 2007 Aaron Seigo <aseigo@kde.org> |
3 | * |
4 | * This program is free software; you can redistribute it and/or modify |
5 | * it under the terms of the GNU Library General Public License as |
6 | * published by the Free Software Foundation; either version 2, 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 Library General Public |
15 | * License along with this program; if not, write to the |
16 | * Free Software Foundation, Inc., |
17 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef PLASMA_VIEW_H |
21 | #define PLASMA_VIEW_H |
22 | |
23 | #include <QtGui/QApplication> |
24 | #include <QtGui/QGraphicsView> |
25 | |
26 | #include <kconfiggroup.h> |
27 | |
28 | #include <plasma/plasma_export.h> |
29 | |
30 | namespace Plasma |
31 | { |
32 | |
33 | class Containment; |
34 | class Corona; |
35 | class ViewPrivate; |
36 | |
37 | /** |
38 | * @class View plasma/view.h <Plasma/View> |
39 | * |
40 | * @short A QGraphicsView for a single Containment |
41 | * |
42 | * Each View is associated with a Plasma::Containment and tracks geometry |
43 | * changes, maps to the current desktop (if any) among other helpful |
44 | * utilities. It isn't stricly required to use a Plasma::View with Plasma |
45 | * enabled applications, but it can make some things easier. |
46 | */ |
47 | class PLASMA_EXPORT View : public QGraphicsView |
48 | { |
49 | Q_OBJECT |
50 | |
51 | public: |
52 | /** |
53 | * Constructs a view for a given contanment. An Id is automatically |
54 | * assigned to the View. |
55 | * |
56 | * @param containment the containment to center the view on |
57 | * @param parent the parent object for this view |
58 | */ |
59 | explicit View(Containment *containment, QWidget *parent = 0); |
60 | |
61 | /** |
62 | * Constructs a view for a given contanment. |
63 | * |
64 | * @param containment the containment to center the view on |
65 | * @param viewId the id to assign to this view |
66 | * @param parent the parent object for this view |
67 | */ |
68 | View(Containment *containment, int viewId, QWidget *parent = 0); |
69 | |
70 | ~View(); |
71 | |
72 | /** |
73 | * Sets whether or not to draw the containment wallpaper when painting |
74 | * on this item |
75 | */ |
76 | void setWallpaperEnabled(bool draw); |
77 | |
78 | /** |
79 | * @return whether or not containments should draw wallpaper |
80 | */ |
81 | bool isWallpaperEnabled() const; |
82 | |
83 | /** |
84 | * Sets which screen this view is associated with, if any. |
85 | * This will also set the containment if a valid screen is specified |
86 | * |
87 | * @param screen the physical screen number; -1 for no screen |
88 | * @param desktop the virtual desktop number, or -1 for all virtual desktops |
89 | */ |
90 | void setScreen(int screen, int desktop = -1); |
91 | |
92 | /** |
93 | * Returns the screen this view is associated with |
94 | * |
95 | * @return the xinerama screen number, or -1 for none |
96 | */ |
97 | int screen() const; |
98 | |
99 | /** |
100 | * The virtual desktop this view is associated with |
101 | * |
102 | * @return the desktop number, -1 for all desktops and less than -1 for none |
103 | */ |
104 | int desktop() const; |
105 | |
106 | /** |
107 | * The virtual desktop this view is actually being viewed on |
108 | * |
109 | * @return the desktop number (always valid, never < 0) |
110 | */ |
111 | int effectiveDesktop() const; |
112 | |
113 | /** |
114 | * @return the containment associated with this view, or 0 if none is |
115 | */ |
116 | Containment *containment() const; |
117 | |
118 | /** |
119 | * Swaps one containment with another. |
120 | * |
121 | * @param existing the existing containment to swap out |
122 | * @param name the plugin name for the new containment. |
123 | * @param args argument list to pass to the containment |
124 | * @return the new containment |
125 | */ |
126 | Containment *swapContainment(Plasma::Containment *existing, |
127 | const QString &name, |
128 | const QVariantList &args = QVariantList()); |
129 | |
130 | /** |
131 | * Swap the containment for this view, which will also cause the view |
132 | * to track the geometry of the containment. |
133 | * |
134 | * @param name the plugin name for the new containment. |
135 | * @param args argument list to pass to the containment |
136 | */ |
137 | Containment *swapContainment(const QString &name, |
138 | const QVariantList &args = QVariantList()); |
139 | |
140 | /** |
141 | * Set whether or not the view should adjust its size when the associated |
142 | * containment does. |
143 | * @param trackChanges true to synchronize the view's size with the containment's |
144 | * (this is the default behaviour), false to ignore containment size changes |
145 | */ |
146 | void setTrackContainmentChanges(bool trackChanges); |
147 | |
148 | /** |
149 | * @return whether or not the view tracks changes to the containment |
150 | */ |
151 | bool trackContainmentChanges(); |
152 | |
153 | /** |
154 | * @param pos the position in screen coordinates. |
155 | * @return the Plasma::View that is at position pos. |
156 | */ |
157 | static View * topLevelViewAt(const QPoint & pos); |
158 | |
159 | /** |
160 | * @return the id of the View set in the constructor |
161 | */ |
162 | int id() const; |
163 | |
164 | Q_SIGNALS: |
165 | /** |
166 | * This signal is emitted whenever the containment being viewed has |
167 | * changed its geometry, but before the View has shifted the viewd scene rect |
168 | * to the new geometry. This is useful for Views which want to keep |
169 | * their rect() in sync with the containment'sa |
170 | */ |
171 | void sceneRectAboutToChange(); |
172 | |
173 | /** |
174 | * This signal is emitted whenever the containment being viewed has |
175 | * changed its geometry, and after the View has shifted the viewd scene rect |
176 | * to the new geometry. This is useful for Views which want to keep |
177 | * their rect() in sync with the containment's. |
178 | */ |
179 | void sceneRectChanged(); |
180 | |
181 | /** |
182 | * This is emitted after the containment is destroyed, for views that need to do something about |
183 | * it (like find a new one). |
184 | */ |
185 | void lostContainment(); |
186 | |
187 | public Q_SLOTS: |
188 | /** |
189 | * Sets the containment for this view, which will also cause the view |
190 | * to track the geometry of the containment. |
191 | * |
192 | * @param containment the containment to center the view on |
193 | */ |
194 | virtual void setContainment(Plasma::Containment *containment); |
195 | |
196 | protected: |
197 | /** |
198 | * @return a KConfigGroup in the application's config file unique to the view |
199 | */ |
200 | KConfigGroup config() const; |
201 | |
202 | |
203 | /** |
204 | * Requests that the config be synchronized to disk |
205 | */ |
206 | void configNeedsSaving() const; |
207 | |
208 | private: |
209 | ViewPrivate * const d; |
210 | |
211 | Q_PRIVATE_SLOT(d, void updateSceneRect()) |
212 | Q_PRIVATE_SLOT(d, void containmentDestroyed()) |
213 | Q_PRIVATE_SLOT(d, void containmentScreenChanged(int, int, Plasma::Containment *)) |
214 | Q_PRIVATE_SLOT(d, void privateInit()) |
215 | |
216 | friend class ViewPrivate; |
217 | }; |
218 | |
219 | } // namespace Plasma |
220 | |
221 | #endif |
222 | |
223 | |