QDoc port

.gitlab-ci.yml

@@ -7,6 +7,3 @@ include:
       - /gitlab-templates/reuse-lint.yml
       - /gitlab-templates/linux-qt6.yml
       - /gitlab-templates/freebsd-qt6.yml
-      - /gitlab-templates/xml-lint.yml
-      - /gitlab-templates/yaml-lint.yml
-      - /gitlab-templates/linux-qt6-next.yml

.kde-ci.yml

@@ -2,11 +2,11 @@
 # SPDX-License-Identifier: CC0-1.0
 
 Dependencies:
- - 'on': ['@all']
-   'require':
+- 'on': ['@all']
+  'require':
     'frameworks/extra-cmake-modules': '@latest-kf6'
     'third-party/wayland': '@latest'
     'third-party/wayland-protocols': '@latest'
 
 Options:
- require-passing-tests-on: ['Linux', 'FreeBSD', 'Windows']
+  require-passing-tests-on: ['Linux', 'FreeBSD', 'Windows']

CMakeLists.txt

@@ -4,13 +4,13 @@
 cmake_minimum_required(VERSION 3.16)
 
 project(layershellqt)
-set(PROJECT_VERSION "6.3.80")
+set(PROJECT_VERSION "6.1.90")
 set(PROJECT_VERSION_MAJOR 6)
 
 set(CMAKE_C_STANDARD 99)
 
 set(QT_MIN_VERSION "6.7.0")
-set(KF6_MIN_VERSION "6.10.0")
+set(KF6_MIN_VERSION "6.5.0")
 set(KDE_COMPILERSETTINGS_LEVEL "5.82")
 
 set(CMAKE_CXX_STANDARD 20)
@@ -32,13 +32,9 @@ include(KDEClangFormat)
 include(ECMQtDeclareLoggingCategory)
 include(ECMQmlModule)
 include(KDEGitCommitHooks)
+include(ECMGenerateQDoc)
 
 find_package(Qt6 ${QT_MIN_VERSION} CONFIG REQUIRED COMPONENTS WaylandClient Qml)
-
-if (Qt6WaylandClient_VERSION VERSION_GREATER_EQUAL "6.10.0")
-    find_package(Qt6WaylandClientPrivate ${REQUIRED_QT_VERSION} REQUIRED NO_MODULE)
-endif()
-
 find_package(WaylandScanner REQUIRED)
 find_package(Wayland 1.3 COMPONENTS Client Server)
 find_package(WaylandProtocols REQUIRED)
@@ -60,8 +56,8 @@ kde_clang_format(${ALL_CLANG_FORMAT_SOURCE_FILES})
 
 kde_configure_git_pre_commit_hook(CHECKS CLANG_FORMAT)
 
-ecm_set_disabled_deprecation_versions(QT 6.8.1
-    KF 6.9.0
+ecm_set_disabled_deprecation_versions(QT 6.5
+    KF 5.240
 )
 
 add_subdirectory(src)

metainfo.yaml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: CC0-1.0
 
 maintainer:
-    - vladz
+- vladz
 description: Layer Shell Qt
 platforms:
     - name: Linux

src/CMakeLists.txt

@@ -68,6 +68,8 @@ generate_export_header(LayerShellQtInterface
     EXPORT_FILE_NAME LayerShellQt/layershellqt_export.h
 )
 
+ecm_generate_qdoc(LayerShellQtInterface layershellqt.qdocconf)
+
 install(TARGETS layer-shell
         LIBRARY DESTINATION ${KDE_INSTALL_QTPLUGINDIR}/wayland-shell-integration)
 

src/interfaces/shell.h

@@ -13,12 +13,18 @@
 
 namespace LayerShellQt
 {
-/**
- * Sets the right environment so the shells created from now on use wlr-layer-shell.
+/*!
+ * \class LayerShellQt::Shell
+ * \inmodule LayerShellQt
+ * \inheaderfile LayerShellQt/Shell
+ *
  */
 class LAYERSHELLQT_EXPORT Shell
 {
 public:
+    /*!
+     * Sets the right environment so the shells created from now on use wlr-layer-shell.
+     */
     static void useLayerShell();
 };
 

src/interfaces/window.h

@@ -18,10 +18,18 @@ namespace LayerShellQt
 {
 class WindowPrivate;
 
+/*!
+ * \class LayerShellQt::Window
+ * \inmodule LayerShellQt
+ * \inheaderfile LayerShellQt/Window
+ *
+ * \brief A window.
+ */
 class LAYERSHELLQT_EXPORT Window : public QObject
 {
     Q_OBJECT
     Q_PROPERTY(Anchors anchors READ anchors WRITE setAnchors NOTIFY anchorsChanged)
+    /*! \property LayerShellQt::Window::scope */
     Q_PROPERTY(QString scope READ scope WRITE setScope)
     Q_PROPERTY(QMargins margins READ margins WRITE setMargins NOTIFY marginsChanged)
     Q_PROPERTY(qint32 exclusionZone READ exclusionZone WRITE setExclusiveZone NOTIFY exclusionZoneChanged)
@@ -32,17 +40,24 @@ class LAYERSHELLQT_EXPORT Window : public QObject
 public:
     ~Window() override;
 
+    /*!
+     * \value AnchorNone
+     * \value AnchorTop The top edge of the anchor rectangle
+     * \value AnchorBottom The bottom edge of the anchor rectangle
+     * \value AnchorLeft The left edge of the anchor rectangle
+     * \value AnchorRight The right edge of the anchor rectangle
+     */
     enum Anchor {
         AnchorNone = 0,
-        AnchorTop = 1, ///< The top edge of the anchor rectangle
-        AnchorBottom = 2, ///< The bottom edge of the anchor rectangle
-        AnchorLeft = 4, ///< The left edge of the anchor rectangle
-        AnchorRight = 8, ///< The right edge of the anchor rectangle
+        AnchorTop = 1,
+        AnchorBottom = 2,
+        AnchorLeft = 4,
+        AnchorRight = 8,
     };
     Q_ENUM(Anchor);
     Q_DECLARE_FLAGS(Anchors, Anchor)
 
-    /**
+    /*!
      * This enum type is used to specify the layer where a surface can be put in.
      */
     enum Layer {
@@ -53,7 +68,7 @@ public:
     };
     Q_ENUM(Layer)
 
-    /**
+    /*!
      * This enum type is used to specify how the layer surface handles keyboard focus.
      */
     enum KeyboardInteractivity {
@@ -63,7 +78,7 @@ public:
     };
     Q_ENUM(KeyboardInteractivity)
 
-    /**
+    /*!
      * This enum type is used to specify which screen to place the surface on.
      * ScreenFromQWindow (the default) reads QWindow::screen() while ScreenFromCompositor
      * passes nil and lets the compositor decide.
@@ -95,7 +110,7 @@ public:
     void setScreenConfiguration(ScreenConfiguration screenConfiguration);
     ScreenConfiguration screenConfiguration() const;
 
-    /**
+    /*!
      * Sets a string based identifier for this window.
      * This may be used by a compositor to determine stacking
      * order within a given layer.
@@ -103,9 +118,17 @@ public:
      * May also be referred to as a role
      */
     void setScope(const QString &scope);
+
+    /*!
+     * A string based identifier for this window.
+     * This may be used by a compositor to determine stacking
+     * order within a given layer.
+     *
+     * May also be referred to as a role
+     */
     QString scope() const;
 
-    /**
+    /*!
      * Whether the QWindow should be closed when the layer surface is dismissed by the compositor.
      * For example, if the associated screen has been removed.
      *
@@ -114,7 +137,7 @@ public:
     void setCloseOnDismissed(bool close);
     bool closeOnDismissed() const;
 
-    /**
+    /*!
      * Gets the LayerShell Window for a given Qt Window
      * Ownership is not transferred
      */

src/layershellqt.qdoc

@@ -0,0 +1,72 @@
+/*!
+    \module LayerShellQt
+    \title LayerShellQt C++ Classes
+
+    \cmakepackage LayerShellQt
+    \cmaketargetitem LayerShellQt::Interface
+*/
+
+/*!
+    \namespace LayerShellQt
+    \inmodule LayerShellQt
+
+    Stuff
+*/
+
+/*!
+    \qmlmodule org.kde.layershell
+    \title LayerShellQt QML Types
+*/
+
+/*!
+    \qmltype Window
+    \inqmlmodule org.kde.layershell
+
+    \nativetype LayerShellQt::Window
+*/
+
+/*!
+    \qmlproperty string Window::scope
+
+    A scope.
+*/
+
+/*!
+    \qmlproperty int Window::margins.top
+    \qmlproperty int Window::margins.bottom
+    \qmlproperty int Window::margins.left
+    \qmlproperty int Window::margins.right
+
+    Margins
+*/
+
+/*!
+    \qmlproperty int Window::exclusionZone
+*/
+
+/*!
+    \page layershellqt-index.html
+    \title LayerShellQt
+
+    Layer Shell
+
+    \section1 Using the Module
+
+    \include {module-use.qdocinc} {using the c++ api}
+
+    \section2 Building with CMake
+
+    \include {module-use.qdocinc} {building with cmake} {Widgets}
+
+    \section1 API Reference
+
+    \list
+        \li \l{LayerShellQt C++ Classes}
+        \li \l{LayerShellQt QML Types}
+    \endlist
+
+    \section1 Licenses
+
+    TODO
+*/
+

src/layershellqt.qdocconf

@@ -0,0 +1,30 @@
+include($KDE_DOCS/global/qt-module-defaults.qdocconf)
+
+project = LayerShellQt
+description = Qt component to allow applications to make use of the Wayland wl-layer-shell protocol
+
+documentationinheaders = true
+
+headerdirs = .
+
+headers.fileextensions = "*.qdoc *.h"
+
+outputdir  = doc/html
+outputformats = HTML
+
+depends += \
+    qtcore
+
+qhp.projects            = LayerShellQt
+
+qhp.LayerShellQt.file                = layershellqt.qhp
+qhp.LayerShellQt.namespace           = org.kde.layershellqt.$QT_VERSION_TAG
+qhp.LayerShellQt.virtualFolder       = layershellqt
+qhp.LayerShellQt.indexTitle          = LayerShellQt
+qhp.LayerShellQt.indexRoot           =
+
+qhp.LayerShellQt.subprojects         = classes
+qhp.LayerShellQt.subprojects.classes.title = C++ Classes
+qhp.LayerShellQt.subprojects.classes.indexTitle = LayerShellQt C++ Classes
+qhp.LayerShellQt.subprojects.classes.selectors = class fake:headerfile
+qhp.LayerShellQt.subprojects.classes.sortPages = true

src/qwaylandlayershellintegration.cpp

@@ -15,7 +15,7 @@
 namespace LayerShellQt
 {
 QWaylandLayerShellIntegration::QWaylandLayerShellIntegration()
-    : QWaylandShellIntegrationTemplate<QWaylandLayerShellIntegration>(6)
+    : QWaylandShellIntegrationTemplate<QWaylandLayerShellIntegration>(5)
     , m_xdgActivation(new QWaylandXdgActivationV1)
 {
 }

src/qwaylandlayersurface.cpp

@@ -74,11 +74,6 @@ QWaylandLayerSurface::~QWaylandLayerSurface()
     destroy();
 }
 
-bool QWaylandLayerSurface::isExposed() const
-{
-    return m_configured && !m_waitingForRearrange;
-}
-
 void QWaylandLayerSurface::zwlr_layer_surface_v1_closed()
 {
     if (m_interface->closeOnDismissed()) {
@@ -86,15 +81,6 @@ void QWaylandLayerSurface::zwlr_layer_surface_v1_closed()
     }
 }
 
-void QWaylandLayerSurface::zwlr_layer_surface_v1_rearranged(uint32_t serial)
-{
-    qDebug() << serial << m_arrangeSerial;
-    if (m_arrangeSerial == serial) {
-        qDebug() << "unset rearrange";
-        m_waitingForRearrange = false;
-    }
-}
-
 void QWaylandLayerSurface::zwlr_layer_surface_v1_configure(uint32_t serial, uint32_t width, uint32_t height)
 {
     ack_configure(serial);
@@ -103,6 +89,7 @@ void QWaylandLayerSurface::zwlr_layer_surface_v1_configure(uint32_t serial, uint
     if (!m_configured) {
         m_configured = true;
         applyConfigure();
+        sendExpose();
     } else {
         // Later configures are resizes, so we have to queue them up for a time when we
         // are not painting to the window.
@@ -130,7 +117,6 @@ void QWaylandLayerSurface::applyConfigure()
 #if QT_VERSION < QT_VERSION_CHECK(6, 9, 0)
     m_configuring = false;
 #endif
-    window()->updateExposure();
 }
 
 void QWaylandLayerSurface::setDesiredSize(const QSize &size)
@@ -146,16 +132,6 @@ void QWaylandLayerSurface::setDesiredSize(const QSize &size)
         effectiveSize.setHeight(0);
     }
     set_size(effectiveSize.width(), effectiveSize.height());
-
-    static quint32 token = 0;
-    m_waitingForRearrange = true;
-    m_arrangeSerial = ++token;
-    set_arrange_token(m_arrangeSerial);
-    window()->updateExposure();
-    if (!window()->isExposed()) {
-        window()->commit(); // FIXME: ugly
-    }
-    qDebug() << "request reposition" << m_arrangeSerial;
 }
 
 void QWaylandLayerSurface::setAnchor(uint anchor)

src/qwaylandlayersurface_p.h

@@ -28,7 +28,10 @@ public:
     QWaylandLayerSurface(QWaylandLayerShellIntegration *shell, QtWaylandClient::QWaylandWindow *window);
     ~QWaylandLayerSurface() override;
 
-    bool isExposed() const override;
+    bool isExposed() const override
+    {
+        return m_configured;
+    }
     void attachPopup(QtWaylandClient::QWaylandShellSurface *popup) override;
 
     void setDesiredSize(const QSize &size);
@@ -54,7 +57,6 @@ private:
     void sendExpose();
     void zwlr_layer_surface_v1_configure(uint32_t serial, uint32_t width, uint32_t height) override;
     void zwlr_layer_surface_v1_closed() override;
-    void zwlr_layer_surface_v1_rearranged(uint32_t token) override;
 
     QWaylandLayerShellIntegration *m_shell;
     LayerShellQt::Window *m_interface;
@@ -66,8 +68,6 @@ private:
 #if QT_VERSION < QT_VERSION_CHECK(6, 9, 0)
     bool m_configuring = false;
 #endif
-    quint32 m_arrangeSerial = 0;
-    bool m_waitingForRearrange = false;
 };
 
 }

src/wlr-layer-shell-unstable-v1.xml

@@ -25,7 +25,7 @@
     THIS SOFTWARE.
   </copyright>
 
-  <interface name="zwlr_layer_shell_v1" version="6">
+  <interface name="zwlr_layer_shell_v1" version="5">
     <description summary="create surfaces that are layers of the desktop">
       Clients can use this interface to assign the surface_layer role to
       wl_surfaces. Such surfaces are assigned to a "layer" of the output and
@@ -100,7 +100,7 @@
     </request>
   </interface>
 
-  <interface name="zwlr_layer_surface_v1" version="6">
+  <interface name="zwlr_layer_surface_v1" version="5">
     <description summary="layer metadata interface">
       An interface that may be implemented by a wl_surface, for surfaces that
       are designed to be rendered as a layer of a stacked desktop-like
@@ -203,21 +203,85 @@
       <arg name="left" type="int"/>
     </request>
 
+    <enum name="keyboard_interactivity">
+      <description summary="types of keyboard interaction possible for a layer shell surface">
+        Types of keyboard interaction possible for layer shell surfaces. The
+        rationale for this is twofold: (1) some applications are not interested
+        in keyboard events and not allowing them to be focused can improve the
+        desktop experience; (2) some applications will want to take exclusive
+        keyboard focus.
+      </description>
+
+      <entry name="none" value="0">
+        <description summary="no keyboard focus is possible">
+          This value indicates that this surface is not interested in keyboard
+          events and the compositor should never assign it the keyboard focus.
+
+          This is the default value, set for newly created layer shell surfaces.
+
+          This is useful for e.g. desktop widgets that display information or
+          only have interaction with non-keyboard input devices.
+        </description>
+      </entry>
+      <entry name="exclusive" value="1">
+        <description summary="request exclusive keyboard focus">
+          Request exclusive keyboard focus if this surface is above the shell surface layer.
+
+          For the top and overlay layers, the seat will always give
+          exclusive keyboard focus to the top-most layer which has keyboard
+          interactivity set to exclusive. If this layer contains multiple
+          surfaces with keyboard interactivity set to exclusive, the compositor
+          determines the one receiving keyboard events in an implementation-
+          defined manner. In this case, no guarantee is made when this surface
+          will receive keyboard focus (if ever).
+
+          For the bottom and background layers, the compositor is allowed to use
+          normal focus semantics.
+
+          This setting is mainly intended for applications that need to ensure
+          they receive all keyboard events, such as a lock screen or a password
+          prompt.
+        </description>
+      </entry>
+      <entry name="on_demand" value="2" since="4">
+        <description summary="request regular keyboard focus semantics">
+          This requests the compositor to allow this surface to be focused and
+          unfocused by the user in an implementation-defined manner. The user
+          should be able to unfocus this surface even regardless of the layer
+          it is on.
+
+          Typically, the compositor will want to use its normal mechanism to
+          manage keyboard focus between layer shell surfaces with this setting
+          and regular toplevels on the desktop layer (e.g. click to focus).
+          Nevertheless, it is possible for a compositor to require a special
+          interaction to focus or unfocus layer shell surfaces (e.g. requiring
+          a click even if focus follows the mouse normally, or providing a
+          keybinding to switch focus between layers).
+
+          This setting is mainly intended for desktop shell components (e.g.
+          panels) that allow keyboard interaction. Using this option can allow
+          implementing a desktop shell that can be fully usable without the
+          mouse.
+        </description>
+      </entry>
+    </enum>
+
     <request name="set_keyboard_interactivity">
       <description summary="requests keyboard events">
-        Set to 1 to request that the seat send keyboard events to this layer
-        surface. For layers below the shell surface layer, the seat will use
-        normal focus semantics. For layers above the shell surface layers, the
-        seat will always give exclusive keyboard focus to the top-most layer
-        which has keyboard interactivity set to true.
+        Set how keyboard events are delivered to this surface. By default,
+        layer shell surfaces do not receive keyboard events; this request can
+        be used to change this.
+
+        This setting is inherited by child surfaces set by the get_popup
+        request.
 
         Layer surfaces receive pointer, touch, and tablet events normally. If
         you do not want to receive them, set the input region on your surface
         to an empty region.
 
-        Events is double-buffered, see wl_surface.commit.
+        Keyboard interactivity is double-buffered, see wl_surface.commit.
       </description>
-      <arg name="keyboard_interactivity" type="uint"/>
+      <arg name="keyboard_interactivity" type="uint" enum="keyboard_interactivity"/>
     </request>
 
     <request name="get_popup">
@@ -302,6 +366,7 @@
       <entry name="invalid_surface_state" value="0" summary="provided surface state is invalid"/>
       <entry name="invalid_size" value="1" summary="size is invalid"/>
       <entry name="invalid_anchor" value="2" summary="anchor bitfield is invalid"/>
+      <entry name="invalid_keyboard_interactivity" value="3" summary="keyboard interactivity is invalid"/>
       <entry name="invalid_exclusive_edge" value="4" summary="exclusive edge is invalid given the surface anchors"/>
     </enum>
 
@@ -338,13 +403,5 @@
       </description>
       <arg name="edge" type="uint"/>
     </request>
-
-    <request name="set_arrange_token" since="6">
-      <arg name="token" type="uint"/>
-    </request>
-
-    <event name="rearranged" since="6">
-      <arg name="token" type="uint"/>
-    </event>
   </interface>
 </protocol>