i3/sway: add documentation, fix module.md and impl monitorFor

Author: nydragon

CMakeLists.txt

@@ -56,7 +56,7 @@ boption(HYPRLAND_IPC " Hyprland IPC" ON REQUIRES HYPRLAND)
 boption(HYPRLAND_GLOBAL_SHORTCUTS " Hyprland Global Shortcuts" ON REQUIRES HYPRLAND)
 boption(HYPRLAND_FOCUS_GRAB " Hyprland Focus Grabbing" ON REQUIRES HYPRLAND)
 boption(I3 " I3/Sway" ON)
-boption(I3_IPC " I3/Sway IPC" ON)
+boption(I3_IPC " I3/Sway IPC" ON REQUIRES I3)
 boption(X11 "X11" ON)
 boption(SERVICE_STATUS_NOTIFIER "System Tray" ON)
 boption(SERVICE_PIPEWIRE "PipeWire" ON)

src/x11/i3/CMakeLists.txt

@@ -15,6 +15,8 @@ qt_add_qml_module(quickshell-i3
 IMPORTS ${I3_MODULES}
 )
 
+install_qml_module(quickshell-i3)
+
 qs_pch(quickshell-i3)
 qs_pch(quickshell-i3plugin)
 

src/x11/i3/ipc/connection.cpp

@@ -20,6 +20,7 @@
 #include <qtypes.h>
 
 #include "../../../core/model.hpp"
+#include "../../../core/qmlscreen.hpp"
 #include "connection.hpp"
 #include "monitor.hpp"
 #include "workspace.hpp"
@@ -196,6 +197,7 @@ void I3Ipc::eventSocketStateChanged(QLocalSocket::LocalSocketState state) {
 
 QString I3Ipc::socketPath() const { return this->mSocketPath; }
 I3Workspace* I3Ipc::focusedWorkspace() const { return this->mFocusedWorkspace; }
+I3Monitor* I3Ipc::focusedMonitor() const { return this->mFocusedMonitor; }
 
 void I3Ipc::setFocusedWorkspace(I3Workspace* workspace) {
 if (workspace == this->mFocusedWorkspace) return;
@@ -444,6 +446,12 @@ void I3Ipc::handleWorkspaceEvent(I3IpcEvent* event) {
 }
 }
 
+I3Monitor* I3Ipc::monitorFor(QuickshellScreenInfo* screen) {
+if (screen == nullptr) return nullptr;
+
+return this->findMonitorByName(screen->name());
+}
+
 I3Workspace* I3Ipc::findWorkspaceByName(const QString& name) {
 auto mList = this->mWorkspaces.valueList();
 auto workspaceIter = std::find_if(mList.begin(), mList.end(), [name](const I3Workspace* m) {

src/x11/i3/ipc/connection.hpp

@@ -11,6 +11,7 @@
 #include <qtypes.h>
 
 #include "../../../core/model.hpp"
+#include "../../../core/qmlscreen.hpp"
 
 namespace qs::i3::ipc {
 
@@ -39,7 +40,7 @@ enum EventCode {
 
 using Event = std::tuple<EventCode, QJsonDocument>;
 
-///! I3 IPC Events
+///! I3/Sway IPC Events
 /// Emitted by @@I3.rawEvent(s)
 class I3IpcEvent: public QObject {
 Q_OBJECT;
@@ -86,6 +87,9 @@ class I3Ipc: public QObject {
 void refreshWorkspaces();
 void refreshMonitors();
 
+I3Monitor* monitorFor(QuickshellScreenInfo* screen);
+
+[[nodiscard]] I3Monitor* focusedMonitor() const;
 [[nodiscard]] I3Workspace* focusedWorkspace() const;
 [[nodiscard]] ObjectModel<I3Monitor>* monitors();
 [[nodiscard]] ObjectModel<I3Workspace>* workspaces();

src/x11/i3/ipc/monitor.hpp

@@ -6,20 +6,43 @@
 
 namespace qs::i3::ipc {
 
+///! I3/Sway monitors
 class I3Monitor: public QObject {
 Q_OBJECT;
 
+/// The ID of this monitor
 Q_PROPERTY(qint32 id READ id NOTIFY idChanged);
+/// The name of this monitor
 Q_PROPERTY(QString name READ name NOTIFY nameChanged);
+/// Wether this monitor is turned on or not
 Q_PROPERTY(bool power READ power NOTIFY powerChanged);
+
+/// The currently active workspace
+/// TODO: replace with a list of all workspaces
 Q_PROPERTY(qs::i3::ipc::I3Workspace* activeWorkspace READ activeWorkspace NOTIFY
  activeWorkspaceChanged);
+
+/// The X coordinate of this monitor inside the monitor layout
 Q_PROPERTY(qint32 x READ x NOTIFY xChanged);
+
+/// The Y coordinate of this monitor inside the monitor layout
 Q_PROPERTY(qint32 y READ y NOTIFY yChanged);
+
+/// The width in pixels of this monitor
 Q_PROPERTY(qint32 width READ width NOTIFY widthChanged);
+
+/// The height in pixels of this monitor
 Q_PROPERTY(qint32 height READ height NOTIFY heightChanged);
+
+/// The scaling factor of this monitor, 1 means it runs at native resolution
 Q_PROPERTY(qreal scale READ scale NOTIFY scaleChanged);
+
+/// Whether this monitor is currently in focus
 Q_PROPERTY(bool focused READ focused NOTIFY focusedChanged);
+
+/// Last JSON returned for this monitor, as a JavaScript object.
+///
+/// This updates every time Quickshell receives an `output` event from i3/Sway
 Q_PROPERTY(QVariantMap lastIpcObject READ lastIpcObject NOTIFY lastIpcObjectChanged);
 
 QML_ELEMENT;

src/x11/i3/ipc/qml.cpp

@@ -4,6 +4,7 @@
 #include <qstring.h>
 
 #include "../../../core/model.hpp"
+#include "../../../core/qmlscreen.hpp"
 #include "connection.hpp"
 #include "workspace.hpp"
 
@@ -36,4 +37,18 @@ ObjectModel<I3Workspace>* I3IpcQml::workspaces() { return I3Ipc::instance()->wor
 
 I3Workspace* I3IpcQml::focusedWorkspace() { return I3Ipc::instance()->focusedWorkspace(); }
 
+I3Monitor* I3IpcQml::focusedMonitor() { return I3Ipc::instance()->focusedMonitor(); }
+
+I3Workspace* I3IpcQml::findWorkspaceByName(const QString& name) {
+return I3Ipc::instance()->findWorkspaceByName(name);
+}
+
+I3Monitor* I3IpcQml::findMonitorByName(const QString& name) {
+return I3Ipc::instance()->findMonitorByName(name);
+}
+
+I3Monitor* I3IpcQml::monitorFor(QuickshellScreenInfo* screen) {
+return I3Ipc::instance()->monitorFor(screen);
+}
+
 } // namespace qs::i3::ipc

src/x11/i3/ipc/qml.hpp

@@ -3,17 +3,20 @@
 #include <qobject.h>
 
 #include "../../../core/doc.hpp"
+#include "../../../core/qmlscreen.hpp"
 #include "connection.hpp"
 
 namespace qs::i3::ipc {
 
+///! I3/Sway IPC integration
 class I3IpcQml: public QObject {
 Q_OBJECT;
 // clang-format off
 /// Path to the I3 socket
 Q_PROPERTY(QString socketPath READ socketPath CONSTANT);
 
 Q_PROPERTY(qs::i3::ipc::I3Workspace* focusedWorkspace READ focusedWorkspace NOTIFY focusedWorkspaceChanged);
+Q_PROPERTY(qs::i3::ipc::I3Monitor* focusedMonitor READ focusedMonitor NOTIFY focusedMonitorChanged);
 /// All I3 monitors.
 QSDOC_TYPE_OVERRIDE(ObjectModel<qs::i3::ipc::I3Monitor>*);
 Q_PROPERTY(UntypedObjectModel* monitors READ monitors CONSTANT);
@@ -27,7 +30,7 @@ class I3IpcQml: public QObject {
 public:
 explicit I3IpcQml();
 
-/// Execute  a I3 command [man 5 I3]
+/// Execute an I3/Sway command [man 5 sway](https://man.archlinux.org/man/sway.5.en#COMMANDS)
 Q_INVOKABLE static void dispatch(const QString& request);
 
 /// Refresh monitor information.
@@ -36,14 +39,35 @@ class I3IpcQml: public QObject {
 /// Refresh workspace information.
 Q_INVOKABLE static void refreshWorkspaces();
 
+/// Find an I3Workspace using its name, returns null if the workspace doesn't exist.
+Q_INVOKABLE static I3Workspace* findWorkspaceByName(const QString& name);
+
+/// Find an I3Monitor using its name, returns null if the monitor doesn't exist.
+Q_INVOKABLE static I3Monitor* findMonitorByName(const QString& name);
+
+/// Return the i3/Sway monitor associated with `screen`
+Q_INVOKABLE static I3Monitor* monitorFor(QuickshellScreenInfo* screen);
+
+/// The path to the I3 or Sway socket currently being used
 [[nodiscard]] static QString socketPath();
+
+/// All I3Monitors
 [[nodiscard]] static ObjectModel<I3Monitor>* monitors();
+
+/// All I3Workspaces
 [[nodiscard]] static ObjectModel<I3Workspace>* workspaces();
+
+/// The currently focused Workspace
 [[nodiscard]] static I3Workspace* focusedWorkspace();
+
+/// The currently focused Monitor
+[[nodiscard]] static I3Monitor* focusedMonitor();
+
 signals:
 void rawEvent(I3IpcEvent* event);
 void connected();
 void focusedWorkspaceChanged();
+void focusedMonitorChanged();
 };
 
 } // namespace qs::i3::ipc

src/x11/i3/ipc/workspace.hpp

@@ -4,15 +4,31 @@
 
 namespace qs::i3::ipc {
 
+///! I3/Sway workspaces
 class I3Workspace: public QObject {
 Q_OBJECT;
 
+/// The ID of this workspace, it is unique for i3/Sway launch
 Q_PROPERTY(qint32 id READ id NOTIFY idChanged);
+
+/// The name of this workspace
 Q_PROPERTY(QString name READ name NOTIFY nameChanged);
+
+/// The number of this workspace
 Q_PROPERTY(qint32 num READ num NOTIFY numChanged);
+
+/// If a window in this workspace has an urgent notification
 Q_PROPERTY(bool urgent READ urgent NOTIFY urgentChanged);
+
+/// If this workspace is the one currently in focus
 Q_PROPERTY(bool focused READ focused NOTIFY focusedChanged);
+
+/// The monitor this workspace is being displayed on
 Q_PROPERTY(qs::i3::ipc::I3Monitor* monitor READ monitor NOTIFY monitorChanged);
+
+/// Last JSON returned for this workspace, as a JavaScript object.
+///
+/// This updates every time we receive a `workspace` event from i3/Sway
 Q_PROPERTY(QVariantMap lastIpcObject READ lastIpcObject NOTIFY lastIpcObjectChanged);
 
 QML_ELEMENT;

src/x11/i3/module.md

@@ -1,9 +1,9 @@
-name = "Quickshell.Sway"
-description = "Sway specific Quickshell types"
+name = "Quickshell.I3"
+description = "I3 specific Quickshell types"
 headers = [
-./ipc/connection.hpp
-./ipc/qml.hpp
-./ipc/workspace.hpp
-./ipc/monitor.hpp
+"ipc/connection.hpp",
+"ipc/qml.hpp",
+"ipc/workspace.hpp",
+"ipc/monitor.hpp",
 ]
----
+-----