Introduce dedicated suspend and resume methods on Compositing interface

The new methods suspend and resume are meant to provide a better way to
influence the current compositing state than toggleCompositing. In
addition an overload setCompositing(bool) is added. The resume method is
implemented in a way that it can be used to try to start the compositor
again in case it failed.

Internally the method suspendResume is dropped as it does the same as
setCompositing just with inverted binary logic and worse name. The
compositingToggled signal is now emitted from within setup and finish to
ensure that especially the compositingToggled(true) signal is only
emitted if the Compositor could start.

Also the updateCompositingBlocking is adjusted to use the new dedicated
suspend and resume methods instead of the toggle method.

REVIEW: 106273

composite.cpp

@@ -245,6 +245,8 @@ void Compositor::slotCompositingOptionsInitialized()
     foreach (Unmanaged * c, Workspace::self()->unmanagedList())
         c->setupCompositing();
 
+    emit compositingToggled(true);
+
     // render at least once
     compositeTimer.stop();
     performCompositing();
@@ -299,6 +301,7 @@ void Compositor::finish()
     while (!Workspace::self()->deletedList().isEmpty())
         Workspace::self()->deletedList().first()->discard(Allowed);
     m_finishing = false;
+    emit compositingToggled(false);
 }
 
 // OpenGL self-check failed, fallback to XRender
@@ -354,13 +357,12 @@ void Compositor::slotReinitialize()
     if (effects) { // setup() may fail
         effects->reconfigure();
     }
-    emit compositingToggled(!m_suspended);
 }
 
 // for the shortcut
 void Compositor::slotToggleCompositing()
 {
-    suspendResume(!m_suspended);
+    setCompositing(m_suspended);
 }
 
 // for the dbus call
@@ -391,7 +393,7 @@ void Compositor::updateCompositeBlocking(Client *c)
     if (c) { // if c == 0 we just check if we can resume
         if (c->isBlockingCompositing()) {
             if (!m_blocked) // do NOT attempt to call suspend(true); from within the eventchain!
-                QMetaObject::invokeMethod(this, "slotToggleCompositing", Qt::QueuedConnection);
+                QMetaObject::invokeMethod(this, "suspend", Qt::QueuedConnection);
             m_blocked = true;
         }
     }
@@ -408,17 +410,37 @@ void Compositor::updateCompositeBlocking(Client *c)
         if (resume) { // do NOT attempt to call suspend(false); from within the eventchain!
             m_blocked = false;
             if (m_suspended)
-                QMetaObject::invokeMethod(this, "slotToggleCompositing", Qt::QueuedConnection);
+                QMetaObject::invokeMethod(this, "resume", Qt::QueuedConnection);
         }
     }
 }
 
-void Compositor::suspendResume(bool suspend)
+void Compositor::suspend()
 {
-    m_suspended = suspend;
+    if (m_suspended) {
+        return;
+    }
+    m_suspended = true;
     finish();
-    setup(); // will do nothing if suspended
+}
-    emit compositingToggled(!m_suspended);
+
+void Compositor::resume()
+{
+    if (!m_suspended && hasScene()) {
+        return;
+    }
+    m_suspended = false;
+    // signal toggled is eventually emitted from within setup
+    setup();
+}
+
+void Compositor::setCompositing(bool active)
+{
+    if (active) {
+        resume();
+    } else {
+        suspend();
+    }
 }
 
 void Compositor::restart()

composite.h

@@ -172,8 +172,62 @@ public Q_SLOTS:
     /**
      * Called from the D-Bus interface. Does the same as slotToggleCompositing with the
      * addition to show a notification on how to revert the compositing state.
+     * @see resume
+     * @see suspend
+     * @deprecated Use suspend or resume instead
      **/
     Q_SCRIPTABLE void toggleCompositing();
+    /**
+     * @brief Suspends the Compositor if it is currently active.
+     *
+     * Note: it is possible that the Compositor is not able to suspend. Use @link isActive to check
+     * whether the Compositor has been suspended.
+     *
+     * @return void
+     * @see resume
+     * @see isActive
+     **/
+    Q_SCRIPTABLE void suspend();
+    /**
+     * @brief Resumes the Compositor if it is currently suspended.
+     *
+     * Note: it is possible that the Compositor cannot be resumed, that is there might be Clients
+     * blocking the usage of Compositing or the Scene might be broken. Use @link isActive to check
+     * whether the Compositor has been resumed. Also check @link isCompositingPossible and
+     * @link isOpenGLBroken.
+     *
+     * Note: The starting of the Compositor can require some time and is partially done threaded.
+     * After this method returns the setup may not have been completed.
+     *
+     * @return void
+     * @see suspend
+     * @see isActive
+     * @see isCompositingPossible
+     * @see isOpenGLBroken
+     **/
+    Q_SCRIPTABLE void resume();
+    /**
+     * @brief Tries to suspend or resume the Compositor based on @p active.
+     *
+     * In case the Compositor is already in the asked for state this method is doing nothing. In
+     * case it does not match it is tried to either resume or suspend the Compositor.
+     *
+     * Note: these operations may fail. There is no guarantee that after calling this method to
+     * enable/disable the Compositor, it actually changes to the state. Use @link isActive to check
+     * the actual state of the Compositor.
+     *
+     * Note: The starting of the Compositor can require some time and is partially done threaded.
+     * After this method returns the setup may not have been completed.
+     *
+     * @param active Whether the Compositor should be resumed (@c true) or suspended (@c false)
+     * @return void
+     * @see suspend
+     * @see resume
+     * @see isActive
+     * @see isCompositingPossible
+     * @see isOpenGLBroken
+     **/
+    Q_SCRIPTABLE void setCompositing(bool active);
     /**
      * Actual slot to perform the toggling compositing.
      * That is if the Compositor is suspended it will be resumed and if the Compositor is active
@@ -224,13 +278,6 @@ private Q_SLOTS:
 
 private:
     Compositor(QObject *workspace);
-    /**
-     * Suspends or Resumes the Compositor.
-     * That is stops the Scene in case of @p suspend and restores otherwise.
-     * @param suspend If @c true suspends the Compositor, if @c false starts the Compositor.
-     * TODO: split in two methods: suspend and resume
-     **/
-    void suspendResume(bool suspend = true);
     void setCompositeTimer();
     bool windowRepaintsPending() const;
 

org.kde.kwin.Compositing.xml

@@ -11,5 +11,12 @@
     </signal>
     <method name="toggleCompositing">
     </method>
+    <method name="suspend">
+    </method>
+    <method name="resume">
+    </method>
+    <method name="setCompositing">
+      <arg name="active" type="b" direction="in"/>
+    </method>
   </interface>
 </node>