workspace/libs/taskmanager/task.h

   1 /*****************************************************************
   2
   3 Copyright (c) 2000-2001 Matthias Elter <elter@kde.org>
   4 Copyright (c) 2001 Richard Moore <rich@kde.org>
   5
   6 Permission is hereby granted, free of charge, to any person obtaining a copy
   7 of this software and associated documentation files (the "Software"), to deal
   8 in the Software without restriction, including without limitation the rights
   9 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10 copies of the Software, and to permit persons to whom the Software is
  11 furnished to do so, subject to the following conditions:
  12
  13 The above copyright notice and this permission notice shall be included in
  14 all copies or substantial portions of the Software.
  15
  16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  19 AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  20 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22
  23 ******************************************************************/
  24
  25 #ifndef TASK_H
  26 #define TASK_H
  27
  28 // Qt
  29 #include <QtGui/QDrag>
  30 #include <QtGui/QPixmap>
  31 #include <QtGui/QWidget>
  32
  33 // KDE
  34 #include <ksharedptr.h>
  35 #include <kwindowsystem.h>
  36 #include <netwm.h>
  37
  38 namespace TaskManager
  39 {
  40
  41 typedef QList<WId> WindowList;
  42
  43 class Task;
  44 typedef KSharedPtr<Task> TaskPtr;
  45 typedef QVector<TaskPtr> TaskList;
  46 typedef QMap<WId, TaskPtr> TaskDict;
  47
  48 /**
  49  * A dynamic interface to a task (main window).
  50  *
  51  * @see TaskManager
  52  */
  53 class KDE_EXPORT Task: public QObject, public KShared
  54 {
  55     Q_OBJECT
  56     Q_PROPERTY( QString visibleName READ visibleName )
  57     Q_PROPERTY( QString name READ name )
  58     Q_PROPERTY( QString className READ className )
  59     Q_PROPERTY( QString visibleNameWithState READ visibleNameWithState )
  60     Q_PROPERTY( QPixmap pixmap READ pixmap )
  61     Q_PROPERTY( bool maximized READ isMaximized )
  62     Q_PROPERTY( bool minimized READ isMinimized )
  63     // KDE4 deprecated
  64     Q_PROPERTY( bool iconified READ isIconified )
  65     Q_PROPERTY( bool shaded READ isShaded WRITE setShaded )
  66     Q_PROPERTY( bool active READ isActive )
  67     Q_PROPERTY( bool onCurrentDesktop READ isOnCurrentDesktop )
  68     Q_PROPERTY( bool onAllDesktops READ isOnAllDesktops )
  69     Q_PROPERTY( bool alwaysOnTop READ isAlwaysOnTop WRITE setAlwaysOnTop )
  70     Q_PROPERTY( bool modified READ isModified )
  71     Q_PROPERTY( bool demandsAttention READ demandsAttention )
  72     Q_PROPERTY( int desktop READ desktop )
  73     Q_PROPERTY( double thumbnailSize READ thumbnailSize WRITE setThumbnailSize )
  74     Q_PROPERTY( bool hasThumbnail READ hasThumbnail )
  75     Q_PROPERTY( QPixmap thumbnail READ thumbnail )
  76
  77 public:
  78     Task(WId win, QObject *parent, const char *name = 0);
  79     virtual ~Task();
  80
  81     WId window() const;
  82     KWindowInfo info() const;
  83
  84     QString visibleName() const;
  85     QString visibleNameWithState() const;
  86     QString name() const;
  87     QString className();
  88     QString classClass();
  89
  90     /**
  91      * A list of the window ids of all transient windows (dialogs) associated
  92      * with this task.
  93      */
  94     WindowList transients() const;
  95
  96     /**
  97      * Returns a 16x16 (KIconLoader::Small) icon for the task. This method will
  98      * only fall back to a static icon if there is no icon of any size in
  99      * the WM hints.
 100      */
 101     QPixmap pixmap() const;
 102
 103     /**
 104      * Returns the best icon for any of the KIconLoader::StdSizes. If there is no
 105      * icon of the specified size specified in the WM hints, it will try to
 106      * get one using KIconLoader.
 107      *
 108      * <pre>
 109      *   bool gotStaticIcon;
 110      *   QPixmap icon = myTask->icon( KIconLoader::SizeMedium, gotStaticIcon );
 111      * </pre>
 112      *
 113      * @param size Any of the constants in KIconLoader::StdSizes.
 114      * @param isStaticIcon Set to true if KIconLoader was used, false otherwise.
 115      */
 116     QPixmap bestIcon( int size, bool &isStaticIcon );
 117
 118     /**
 119      * Tries to find an icon for the task with the specified size. If there
 120      * is no icon that matches then it will either resize the closest available
 121      * icon or return a null pixmap depending on the value of allowResize.
 122      *
 123      * Note that the last icon is cached, so a sequence of calls with the same
 124      * parameters will only query the NET properties if the icon has changed or
 125      * none was found.
 126      */
 127     QPixmap icon( int width, int height, bool allowResize = false );
 128
 129     /**
 130      * Returns true iff the windows with the specified ids should be grouped
 131      * together in the task list.
 132      */
 133     static bool idMatch(const QString &, const QString &);
 134
 135     // state
 136
 137     /**
 138      * Returns true if the task's window is maximized.
 139      */
 140     bool isMaximized() const;
 141
 142     /**
 143      * Returns true if the task's window is minimized.
 144      */
 145     bool isMinimized() const;
 146
 147     /**
 148      * @deprecated
 149      * Returns true if the task's window is minimized(iconified).
 150      */
 151     bool isIconified() const;
 152
 153     /**
 154      * Returns true if the task's window is shaded.
 155      */
 156     bool isShaded() const;
 157
 158     /**
 159      * Returns true if the task's window is the active window.
 160      */
 161     bool isActive() const;
 162
 163     /**
 164      * Returns true if the task's window is the topmost non-iconified,
 165      * non-always-on-top window.
 166      */
 167     bool isOnTop() const;
 168
 169     /**
 170      * Returns true if the task's window is on the current virtual desktop.
 171      */
 172     bool isOnCurrentDesktop() const;
 173
 174     /**
 175      * Returns true if the task's window is on all virtual desktops.
 176      */
 177     bool isOnAllDesktops() const;
 178
 179     /**
 180      * Returns true if the task's window will remain at the top of the
 181      * stacking order.
 182      */
 183     bool isAlwaysOnTop() const;
 184
 185     /**
 186      * Returns true if the task's window will remain at the bottom of the
 187      * stacking order.
 188      */
 189     bool isKeptBelowOthers() const;
 190
 191     /**
 192      * Returns true if the task's window is in full screen mode
 193      */
 194     bool isFullScreen() const;
 195
 196     /**
 197      * Returns true if the document the task is editing has been modified.
 198      * This is currently handled heuristically by looking for the string
 199      * '[i18n_modified]' in the window title where i18n_modified is the
 200      * word 'modified' in the current language.
 201      */
 202     bool isModified() const ;
 203
 204     /**
 205      * Returns the desktop on which this task's window resides.
 206      */
 207     int desktop() const;
 208
 209     /**
 210      * Returns true if the task is not active but demands user's attention.
 211      */
 212     bool demandsAttention() const;
 213
 214
 215     /**
 216     * Returns true if the window is on the specified screen of a multihead configuration
 217     */
 218     bool isOnScreen( int screen ) const;
 219
 220     /**
 221      * Returns true if the task should be shown in taskbar-like apps
 222      */
 223     bool showInTaskbar() const;
 224
 225     /**
 226      * Returns true if the task should be shown in pager-like apps
 227      */
 228     bool showInPager() const;
 229
 230     /**
 231      * Returns the geometry for this window
 232      */
 233     QRect geometry() const;
 234
 235     // internal
 236
 237     //* @internal
 238     void refresh(unsigned int dirty);
 239     //* @internal
 240     void refreshIcon();
 241     //* @internal
 242     void addTransient( WId w, const NETWinInfo& info );
 243     //* @internal
 244     void removeTransient( WId w );
 245     //* @internal
 246     bool hasTransient(WId w) const;
 247     //* @internal
 248     void updateDemandsAttentionState( WId w );
 249     //* @internal
 250     void setActive(bool a);
 251
 252     // For thumbnails
 253
 254     /**
 255      * Returns the current thumbnail size.
 256      */
 257     double thumbnailSize() const;
 258
 259     /**
 260      * Sets the size for the window thumbnail. For example a size of
 261      * 0.2 indicates the thumbnail will be 20% of the original window
 262      * size.
 263      */
 264     void setThumbnailSize( double size );
 265
 266     /**
 267      * Returns true if this task has a thumbnail. Note that this method
 268      * can only ever return true after a call to updateThumbnail().
 269      */
 270     bool hasThumbnail() const;
 271
 272     /**
 273      * Returns the thumbnail for this task (or a null image if there is
 274      * none).
 275      */
 276     QPixmap thumbnail() const;
 277
 278     QPixmap thumbnail(int maxDimension);
 279
 280     void updateWindowPixmap();
 281
 282 public Q_SLOTS:
 283     // actions
 284
 285     /**
 286      * Maximise the main window of this task.
 287      */
 288     void setMaximized(bool);
 289     void toggleMaximized();
 290
 291     /**
 292      * Restore the main window of the task (if it was iconified).
 293      */
 294     void restore();
 295
 296     /**
 297      * Move the window of this task.
 298      */
 299     void move();
 300
 301     /**
 302      * Resize the window of this task.
 303      */
 304     void resize();
 305
 306     /**
 307      * Iconify the task.
 308      */
 309     void setIconified(bool);
 310     void toggleIconified();
 311
 312     /**
 313      * Close the task's window.
 314      */
 315     void close();
 316
 317     /**
 318      * Raise the task's window.
 319      */
 320     void raise();
 321
 322     /**
 323      * Lower the task's window.
 324      */
 325     void lower();
 326
 327    /**
 328      * Activate the task's window.
 329      */
 330     void activate();
 331
 332     /**
 333      * Perform the action that is most appropriate for this task. If it
 334      * is not active, activate it. Else if it is not the top window, raise
 335      * it. Otherwise, iconify it.
 336      */
 337     void activateRaiseOrIconify();
 338
 339     /**
 340      * If true, the task's window will remain at the top of the stacking order.
 341      */
 342     void setAlwaysOnTop(bool);
 343     void toggleAlwaysOnTop();
 344
 345     /**
 346      * If true, the task's window will remain at the bottom of the stacking order.
 347      */
 348     void setKeptBelowOthers(bool);
 349     void toggleKeptBelowOthers();
 350
 351     /**
 352      * If true, the task's window will enter full screen mode.
 353      */
 354     void setFullScreen(bool);
 355     void toggleFullScreen();
 356
 357     /**
 358      * If true then the task's window will be shaded. Most window managers
 359      * represent this state by displaying on the window's title bar.
 360      */
 361     void setShaded(bool);
 362     void toggleShaded();
 363
 364     /**
 365      * Moves the task's window to the specified virtual desktop.
 366      */
 367     void toDesktop(int);
 368
 369     /**
 370      * Moves the task's window to the current virtual desktop.
 371      */
 372     void toCurrentDesktop();
 373
 374     /**
 375      * This method informs the window manager of the location at which this
 376      * task will be displayed when iconised. It is used, for example by the
 377      * KWin inconify animation.
 378      */
 379     void publishIconGeometry(QRect);
 380
 381     /**
 382      * Tells the task to generate a new thumbnail. When the thumbnail is
 383      * ready the thumbnailChanged() signal will be emitted.
 384      */
 385     void updateThumbnail();
 386
 387 Q_SIGNALS:
 388     /**
 389      * Indicates that this task has changed in some way.
 390      */
 391     void changed();
 392
 393     /**
 394      * Indicates that the icon for this task has changed.
 395      */
 396     void iconChanged();
 397
 398     /**
 399      * Indicates that this task is now the active task.
 400      */
 401     void activated();
 402
 403     /**
 404      * Indicates that this task is no longer the active task.
 405      */
 406     void deactivated();
 407
 408     /**
 409      * Indicates that the thumbnail for this task has changed.
 410      */
 411     void thumbnailChanged();
 412
 413 protected Q_SLOTS:
 414     //* @internal
 415     void generateThumbnail();
 416
 417 protected:
 418     void findWindowFrameId();
 419
 420 private:
 421     class Private;
 422     Private * const d;
 423 };
 424
 425
 426 /**
 427  * Provids a drag object for tasks across desktops.
 428  * FIXME: should be folded into the Task class the same way it has been with
 429  *        AppletInfo and KUrl
 430  */
 431 class KDE_EXPORT TaskDrag : public QDrag
 432 {
 433 public:
 434     /**
 435      * Constructs a task drag object for a task list.
 436      */
 437     explicit TaskDrag(const TaskList& tasks, QWidget* source = 0);
 438     ~TaskDrag();
 439
 440     /**
 441      * Returns true if the mime source can be decoded to a TaskDrag.
 442      */
 443     static bool canDecode( const QMimeData* e );
 444
 445     /**
 446      * Decodes the tasks from the mime source and returns them if successful.
 447      * Otherwise an empty task list is returned.
 448      */
 449     static TaskList decode( const QMimeData* e );
 450
 451 private:
 452     class Private;
 453     Private * const d;
 454 };
 455
 456 } // TaskManager namespace
 457
 458
 459 #endif