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
30namespace Plasma
31{
32
33class Containment;
34class Corona;
35class 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 */
47class PLASMA_EXPORT View : public QGraphicsView
48{
49 Q_OBJECT
50
51public:
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
164Q_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
187public 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
196protected:
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
208private:
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