← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to kwin/tabbox/tabboxhandler.h

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
kwin/tabbox/tabboxhandler.h
 
1
/********************************************************************
 
2
 KWin - the KDE window manager
 
3
 This file is part of the KDE project.
 
4
 
 
5
Copyright (C) 2009 Martin Gräßlin <kde@martin-graesslin.com>
 
6
 
 
7
This program is free software; you can redistribute it and/or modify
 
8
it under the terms of the GNU General Public License as published by
 
9
the Free Software Foundation; either version 2 of the License, or
 
10
(at your option) any later version.
 
11
 
 
12
This program is distributed in the hope that it will be useful,
 
13
but WITHOUT ANY WARRANTY; without even the implied warranty of
 
14
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
15
GNU General Public License for more details.
 
16
 
 
17
You should have received a copy of the GNU General Public License
 
18
along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
19
*********************************************************************/
 
20
 
 
21
#ifndef TABBOXHANDLER_H
 
22
#define TABBOXHANDLER_H
 
23
 
 
24
#include "tabboxconfig.h"
 
25
 
 
26
#include <QModelIndex>
 
27
#include <QPixmap>
 
28
#include <QString>
 
29
#include <X11/Xlib.h>
 
30
#include <fixx11h.h>
 
31
 
 
32
/**
 
33
* @file
 
34
* This file contains the classes which hide KWin core from tabbox.
 
35
* It defines the pure virtual classes TabBoxHandler and TabBoxClient.
 
36
* The classes have to be implemented in KWin Core.
 
37
*
 
38
* @author Martin Gräßlin <kde@martin-graesslin.com>
 
39
* @since 4.4
 
40
*/
 
41
 
 
42
class QKeyEvent;
 
43
 
 
44
namespace KWin
 
45
{
 
46
/**
 
47
* The TabBox is a model based view for displaying a list while switching windows or desktops.
 
48
* This functionality is mostly referred as Alt+Tab. TabBox itself does not provide support for
 
49
* switching windows or desktops. This has to be done outside of TabBox inside an independent controller.
 
50
*
 
51
* The main entrance point to TabBox is the class TabBoxHandler, which has to be subclassed and implemented.
 
52
* The class TabBoxClient, which represents a window client inside TabBox, has to be implemented as well.
 
53
*
 
54
* The behavior of the TabBox is defined by the TabBoxConfig and has to be set in the TabBoxHandler.
 
55
* If the TabBox should be used to switch desktops as well as clients it is sufficient to just provide
 
56
* different TabBoxConfig objects instead of creating an own handler for each mode.
 
57
*
 
58
* In order to use the TabBox the TabBoxConfig has to be set. This defines if the model for desktops or for
 
59
* clients will be used. The model has to be initialized by calling TabBoxHandler::createModel(), as the
 
60
* model is undefined when the TabBox is not active. The TabBox is activated by TabBoxHandler::show().
 
61
* Depending on the current set TabBoxConfig it is possible that an additional outline is shown, the
 
62
* highlight windows effect activated and that the view is not displayed at all. As already mentioned
 
63
* the TabBox does not handle any updating of the selected item. This has to be done by invoking
 
64
* TabBoxHandler::setCurrentIndex(). Nevertheless the TabBoxHandler provides methods to query for the
 
65
* model index or the next or previous item, for a cursor position or for a given item (that is
 
66
* TabBoxClient or desktop). By invoking TabBoxHandler::hide() the view, the optional outline and the
 
67
* optional highlight windows effect are removed. The model is invalidated immediately. So if it is
 
68
* necessary to retrieve the last selected item this has to be done before calling the hide method.
 
69
*
 
70
* The layout of the TabBox View and the items is completely customizable. Therefore TabBox provides
 
71
* a widget LayoutConfig which includes a live preview (in kcmkwin/kwintabbox). The layout of items
 
72
* can be defined by an xml document. That way the user is able to define own custom layouts. The view
 
73
* itself is made up of two widgets: one to show the complete list and one to show only the selected
 
74
* item. This way it is possible to have a view which shows for example a list containing only small
 
75
* icons and nevertheless show the title of the currently selected client.
 
76
*/
 
77
namespace TabBox
 
78
{
 
79
class DesktopModel;
 
80
class ClientModel;
 
81
class TabBoxConfig;
 
82
class TabBoxClient;
 
83
class TabBoxView;
 
84
class TabBoxHandlerPrivate;
 
85
typedef QList< TabBoxClient* > TabBoxClientList;
 
86
 
 
87
/**
 
88
* This class is a wrapper around KWin Workspace. It is used for accessing the
 
89
* required core methods from inside TabBox and has to be implemented in KWin core.
 
90
*
 
91
* @author Martin Gräßlin <kde@martin-graesslin.com>
 
92
* @since 4.4
 
93
*/
 
94
class TabBoxHandler : public QObject
 
95
{
 
96
    Q_OBJECT
 
97
public:
 
98
    TabBoxHandler();
 
99
    virtual ~TabBoxHandler();
 
100
 
 
101
    /**
 
102
    * @return The id of the active screen
 
103
    */
 
104
    virtual int activeScreen() const = 0;
 
105
    /**
 
106
    * @return The current active TabBoxClient or NULL
 
107
    * if there is no active client.
 
108
    */
 
109
    virtual TabBoxClient* activeClient() const = 0;
 
110
    /**
 
111
    * @param client The client which is starting point to find the next client
 
112
    * @return The next TabBoxClient in focus chain
 
113
    */
 
114
    virtual TabBoxClient* nextClientFocusChain(TabBoxClient* client) const = 0;
 
115
    /**
 
116
    * @param client The client whose desktop name should be retrieved
 
117
    * @return The desktop name of the given TabBoxClient. If the client is
 
118
    * on all desktops the name of current desktop will be returned.
 
119
    */
 
120
    virtual QString desktopName(TabBoxClient* client) const = 0;
 
121
    /**
 
122
    * @param desktop The desktop whose name should be retrieved
 
123
    * @return The desktop name of given desktop
 
124
    */
 
125
    virtual QString desktopName(int desktop) const = 0;
 
126
    /**
 
127
    * @return The number of current desktop
 
128
    */
 
129
    virtual int currentDesktop() const = 0;
 
130
    /**
 
131
    * @return The number of virtual desktops
 
132
    */
 
133
    virtual int numberOfDesktops() const = 0;
 
134
    /**
 
135
    * @param desktop The desktop which is the starting point to find the next desktop
 
136
    * @return The next desktop in the current focus chain.
 
137
    */
 
138
    virtual int nextDesktopFocusChain(int desktop) const = 0;
 
139
 
 
140
    /**
 
141
    * Raise a client (w/o activating it)
 
142
    */
 
143
    virtual void raiseClient(TabBoxClient* c) const = 0;
 
144
 
 
145
    /**
 
146
     * @param c The client to be restacked
 
147
     * @param under The client the other one will be placed below
 
148
     */
 
149
    virtual void restack(TabBoxClient *c, TabBoxClient *under) = 0;
 
150
 
 
151
    /**
 
152
    * @return The current stacking order of TabBoxClients
 
153
    */
 
154
    virtual TabBoxClientList stackingOrder() const = 0;
 
155
    /**
 
156
    * Determines if given client will be added to the list:
 
157
    * <UL>
 
158
    * <LI>Depends on desktop</LI>
 
159
    * <LI>if the client wants to have tab focus.</LI>
 
160
    * <LI>The client won't be added if it has modal dialogs</LI>
 
161
    * <LI>In that case the modal dialog will be returned if it isn't already
 
162
    * included</LI>
 
163
    * <LI>Won't be added if it isn't on active screen when using separate
 
164
    * screen focus</LI>
 
165
    * </UL>
 
166
    * @param client The client to be checked for inclusion
 
167
    * @param desktop The desktop the client should be on. This is irrelevant if allDesktops is set
 
168
    * @param allDesktops Add clients from all desktops or only from current
 
169
    * @return The client to be included in the list or NULL if it isn't to be included
 
170
    */
 
171
    virtual TabBoxClient* clientToAddToList(TabBoxClient* client, int desktop, bool allDesktops) const = 0;
 
172
    /**
 
173
    * @return The first desktop window in the stacking order.
 
174
    */
 
175
    virtual TabBoxClient* desktopClient() const = 0;
 
176
 
 
177
    /**
 
178
    * @return The currently used TabBoxConfig
 
179
    */
 
180
    const TabBoxConfig& config() const;
 
181
    /**
 
182
    * Call this method when you want to change the currently used TabBoxConfig.
 
183
    * It fires the signal configChanged.
 
184
    * @param config Updates the currently used TabBoxConfig to config
 
185
    */
 
186
    void setConfig(const TabBoxConfig& config);
 
187
 
 
188
    /**
 
189
    * Call this method to show the TabBoxView. Depending on current
 
190
    * configuration this method might not do anything.
 
191
    * If highlight windows effect is to be used it will be activated.
 
192
    * If the outline has to be shown, it will be shown.
 
193
    * Highlight windows and outline are not shown if
 
194
    * TabBoxConfig::TabBoxMode is TabBoxConfig::DesktopTabBox.
 
195
    * @see TabBoxConfig::isShowTabBox
 
196
    * @see TabBoxConfig::isHighlightWindows
 
197
    * @see TabBoxConfig::showOutline
 
198
    */
 
199
    void show();
 
200
    /**
 
201
    * Hides the TabBoxView if shown.
 
202
    * Deactivates highlight windows effect if active.
 
203
    * Removes the outline if active.
 
204
    * @see show
 
205
    */
 
206
    void hide(bool abort = false);
 
207
 
 
208
    /**
 
209
    * Sets the current model index in the view and updates
 
210
    * highlight windows and outline if active.
 
211
    * @param index The current Model index
 
212
    */
 
213
    void setCurrentIndex(const QModelIndex& index);
 
214
 
 
215
    /**
 
216
    * Retrieves the next or previous item of the current item.
 
217
    * @param forward next or previous item
 
218
    * @return The next or previous item. If there is no matching item
 
219
    * the current item will be returned.
 
220
    */
 
221
    QModelIndex nextPrev(bool forward) const;
 
222
 
 
223
    /**
 
224
    * Initializes the model based on the current config.
 
225
    * This method has to be invoked before showing the TabBox.
 
226
    * It can also be invoked when clients are added or removed.
 
227
    * In that case partialReset has to be true.
 
228
    *
 
229
    * @param partialReset Keep the currently selected item or regenerate everything
 
230
    */
 
231
    void createModel(bool partialReset = false);
 
232
 
 
233
    /**
 
234
    * @param desktop The desktop whose index should be retrieved
 
235
    * @return The model index of given desktop. If TabBoxMode is not
 
236
    * TabBoxConfig::DesktopTabBox an invalid model index will be returned.
 
237
    */
 
238
    QModelIndex desktopIndex(int desktop) const;
 
239
    /**
 
240
    * @return The current list of desktops.
 
241
    * If TabBoxMode is not TabBoxConfig::DesktopTabBox an empty list will
 
242
    * be returned.
 
243
    * @see DesktopModel::desktopList
 
244
    */
 
245
    QList< int > desktopList() const;
 
246
    /**
 
247
    * @return The desktop for given model index. If the index is not valid
 
248
    * or TabBoxMode is not TabBoxConfig::DesktopTabBox -1 will be returned.
 
249
    * @see DesktopModel::desktopIndex
 
250
    */
 
251
    int desktop(const QModelIndex& index) const;
 
252
    /**
 
253
    * @return The current selected desktop. If there is no selected desktop
 
254
    * or TabBoxMode is not TabBoxConfig::DesktopTabBox -1 will be returned.
 
255
    */
 
256
    int currentSelectedDesktop() const;
 
257
 
 
258
    /**
 
259
    * Handles additional grabbed key events by the TabBox controller.
 
260
    * It is able to handle cursor key presses and to find the item
 
261
    * left/right/above/below of current item.
 
262
    * @param event The key event which has been grabbed
 
263
    * @return Returns the model index of the left, right, above or
 
264
    * below item, if a cursor key has been pressed. If there is no
 
265
    * such item the current item is returned.
 
266
    */
 
267
    virtual QModelIndex grabbedKeyEvent(QKeyEvent* event) const;
 
268
    /**
 
269
    * @param pos The position to be tested in global coordinates
 
270
    * @return True if the view contains the point, otherwise false.
 
271
    */
 
272
    bool containsPos(const QPoint& pos) const;
 
273
    /**
 
274
    * Returns the index at the given position in global coordinates
 
275
    * of the view.
 
276
    * @param pos The position in global coordinates
 
277
    * @return The model index at given position. If there is no item
 
278
    * at the position or the position is not in the view an invalid
 
279
    * model index will be returned;
 
280
    */
 
281
    QModelIndex indexAt(const QPoint& pos) const;
 
282
    /**
 
283
    * @param client The TabBoxClient whose index should be returned
 
284
    * @return Returns the ModelIndex of given TabBoxClient or an invalid ModelIndex
 
285
    * if the model does not contain the given TabBoxClient.
 
286
    * @see ClientModel::index
 
287
    */
 
288
    QModelIndex index(TabBoxClient* client) const;
 
289
    /**
 
290
    * @return Returns the current list of TabBoxClients.
 
291
    * If TabBoxMode is not TabBoxConfig::ClientTabBox an empty list will
 
292
    * be returned.
 
293
    * @see ClientModel::clientList
 
294
    */
 
295
    TabBoxClientList clientList() const;
 
296
    /**
 
297
    * @param index The index of the client to be returned
 
298
    * @return Returns the TabBoxClient at given model index. If
 
299
    * the index is invalid, does not point to a Client or the list
 
300
    * is empty, NULL will be returned.
 
301
    */
 
302
    TabBoxClient* client(const QModelIndex& index) const;
 
303
    /**
 
304
    * @return The first model index. That is the model index at position 0, 0.
 
305
    * It is valid, as desktop has at least one desktop and if there are no
 
306
    * clients an empty item is created.
 
307
    */
 
308
    QModelIndex first() const;
 
309
 
 
310
    /**
 
311
    * @return The tabBoxView Widget
 
312
    */
 
313
    QWidget* tabBoxView() const;
 
314
 
 
315
protected:
 
316
    /**
 
317
     * Show the outline of the current selected window
 
318
     * @param outline The geometry of the window the outline will be shown
 
319
     * @since 4.7
 
320
     **/
 
321
    virtual void showOutline(const QRect &outline) = 0;
 
322
 
 
323
    /**
 
324
     * Hide previously shown outline
 
325
     * @since 4.7
 
326
     **/
 
327
    virtual void hideOutline() = 0;
 
328
 
 
329
    /**
 
330
     * Return outline window ids
 
331
     * @return The outline window ids given in the order left, top, right, bottom
 
332
     * @since 4.7
 
333
     **/
 
334
    virtual QVector<Window> outlineWindowIds() const = 0;
 
335
 
 
336
signals:
 
337
    /**
 
338
    * This signal is fired when the TabBoxConfig changes
 
339
    * @see setConfig
 
340
    */
 
341
    void configChanged();
 
342
 
 
343
private:
 
344
    friend class TabBoxHandlerPrivate;
 
345
    TabBoxHandlerPrivate* d;
 
346
};
 
347
 
 
348
/**
 
349
* This class is a wrapper around a KWin Client. It is used for accessing the
 
350
* required client methods from inside TabBox and has to be implemented in KWin core.
 
351
*
 
352
* @author Martin Gräßlin <kde@martin-graesslin.com>
 
353
* @since 4.4
 
354
*/
 
355
class TabBoxClient
 
356
{
 
357
public:
 
358
    TabBoxClient();
 
359
    virtual ~TabBoxClient();
 
360
 
 
361
    /**
 
362
    * @return The caption of the client
 
363
    */
 
364
    virtual QString caption() const = 0;
 
365
    /**
 
366
    * @param size Requested size of the icon
 
367
    * @return The icon of the client
 
368
    */
 
369
    virtual QPixmap icon(const QSize& size = QSize(32, 32)) const = 0;
 
370
    /**
 
371
    * @return The window Id of the client
 
372
    */
 
373
    virtual WId window() const = 0;
 
374
    /**
 
375
    * @return Minimized state of the client
 
376
    */
 
377
    virtual bool isMinimized() const = 0;
 
378
    virtual int x() const = 0;
 
379
    virtual int y() const = 0;
 
380
    virtual int width() const = 0;
 
381
    virtual int height() const = 0;
 
382
};
 
383
 
 
384
/**
 
385
 * Pointer to the global TabBoxHandler object.
 
386
 **/
 
387
extern TabBoxHandler* tabBox;
 
388
 
 
389
} // namespace TabBox
 
390
} // namespace KWin
 
391
 
 
392
#endif // TABBOXHANDLER_H