/* SPDX-FileCopyrightText: 2018 Marco Martin SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL */ #ifndef KWAYLAND_CLIENT_PLASMAVIRTUALDESKTOP_H #define KWAYLAND_CLIENT_PLASMAVIRTUALDESKTOP_H #include #include "KWayland/Client/kwaylandclient_export.h" struct org_kde_plasma_virtual_desktop_management; struct org_kde_plasma_virtual_desktop; namespace KWayland { namespace Client { class EventQueue; class PlasmaVirtualDesktop; /** * @short Wrapper for the org_kde_plasma_virtual_desktop_management interface. * * This class provides a convenient wrapper for the org_kde_plasma_virtual_desktop_management interface. * * To use this class one needs to interact with the Registry. There are two * possible ways to create the PlasmaVirtualDesktopManagement interface: * @code * PlasmaVirtualDesktopManagement *c = registry->createPlasmaVirtualDesktopManagement(name, version); * @endcode * * This creates the PlasmaVirtualDesktopManagement and sets it up directly. As an alternative this * can also be done in a more low level way: * @code * PlasmaVirtualDesktopManagement *c = new PlasmaVirtualDesktopManagement; * c->setup(registry->bindPlasmaVirtualDesktopManagement(name, version)); * @endcode * * The PlasmaVirtualDesktopManagement can be used as a drop-in replacement for any org_kde_plasma_virtual_desktop_management * pointer as it provides matching cast operators. * @since 5.52 * * @see Registry **/ class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktopManagement : public QObject { Q_OBJECT public: /** * Creates a new PlasmaVirtualDesktopManagement. * Note: after constructing the PlasmaVirtualDesktopManagement it is not yet valid and one needs * to call setup. In order to get a ready to use PlasmaVirtualDesktopManagement prefer using * Registry::createPlasmaVirtualDesktopManagement. **/ explicit PlasmaVirtualDesktopManagement(QObject *parent = nullptr); ~PlasmaVirtualDesktopManagement() override; /** * Setup this PlasmaVirtualDesktopManagement to manage the @p plasmavirtualdesktopmanagement. * When using Registry::createPlasmaVirtualDesktopManagement there is no need to call this * method. **/ void setup(org_kde_plasma_virtual_desktop_management *plasmavirtualdesktopmanagement); /** * @returns @c true if managing a org_kde_plasma_virtual_desktop_management. **/ bool isValid() const; /** * Releases the org_kde_plasma_virtual_desktop_management interface. * After the interface has been released the PlasmaVirtualDesktopManagement instance is no * longer valid and can be setup with another org_kde_plasma_virtual_desktop_management interface. **/ void release(); /** * Destroys the data held by this PlasmaVirtualDesktopManagement. * This method is supposed to be used when the connection to the Wayland * server goes away. If the connection is not valid anymore, it's not * possible to call release anymore as that calls into the Wayland * connection and the call would fail. This method cleans up the data, so * that the instance can be deleted or set up to a new org_kde_plasma_virtual_desktop_management interface * once there is a new connection available. * * It is suggested to connect this method to ConnectionThread::connectionDied: * @code * connect(connection, &ConnectionThread::connectionDied, plasmavirtualdesktopmanagement, &PlasmaVirtualDesktopManagement::destroy); * @endcode * * @see release **/ void destroy(); /** * Sets the @p queue to use for creating objects with this PlasmaVirtualDesktopManagement. **/ void setEventQueue(EventQueue *queue); /** * @returns The event queue to use for creating objects with this PlasmaVirtualDesktopManagement. * The object is owned by the manager and the caller should not delete it. **/ EventQueue *eventQueue(); /** * @returns the PlasmaVirtualDesktop representing the desktop id. * The PlasmaVirtualDesktop instance is guaranteed to be unique for each id. */ PlasmaVirtualDesktop *getVirtualDesktop(const QString &id); /** * Requests for the desktop identified by id to be removed. * The server may or may not acconsent to the request. */ void requestRemoveVirtualDesktop(const QString &id); /** * Ask the server to create a new virtual desktop, and position it at a specified position. * If the position is zero or less, it will be positioned at the beginning, * if the cosition is the count or more, it will be positioned at the end. * @param name The name we want for the desktop * @param position The position for the desktop to be created */ void requestCreateVirtualDesktop(const QString &name, quint32 position = std::numeric_limits::max()); /** * @returns All the existent virtual desktops */ QList desktops() const; /** * @returns How many rows the virtual desktops should be laid out into * @since 5.55 */ quint32 rows() const; operator org_kde_plasma_virtual_desktop_management *(); operator org_kde_plasma_virtual_desktop_management *() const; Q_SIGNALS: void removed(); /** * Emitted when a new desktop has been added */ void desktopCreated(const QString &id, quint32 position); /** * Emitted when a desktop has been removed */ void desktopRemoved(const QString &id); /** * Emitted when the number of rows of virtual desktops has been changed by the server * @since 5.55 */ void rowsChanged(quint32 rows); /** * This event is sent after all other properties has been * sent after binding to the desktop manager object and after any * other property changes done after that. This allows * changes to the org_kde_plasma_virtual_desktop_management properties * to be seen as atomic, even if they happen via multiple events. */ void done(); private: class Private; QScopedPointer d; }; class KWAYLANDCLIENT_EXPORT PlasmaVirtualDesktop : public QObject { Q_OBJECT public: ~PlasmaVirtualDesktop() override; /** * Setup this PlasmaVirtualDesktop to manage the @p plasmavirtualdesktop. * When using PlasmaVirtualDesktopManagement::createPlasmaVirtualDesktop there is no need to call this * method. **/ void setup(org_kde_plasma_virtual_desktop *plasmavirtualdesktop); /** * @returns @c true if managing a org_kde_plasma_virtual_desktop. **/ bool isValid() const; /** * Releases the org_kde_plasma_virtual_desktop interface. * After the interface has been released the PlasmaVirtualDesktop instance is no * longer valid and can be setup with another org_kde_plasma_virtual_desktop interface. **/ void release(); /** * Destroys the data held by this PlasmaVirtualDesktop. * This method is supposed to be used when the connection to the Wayland * server goes away. If the connection is not valid anymore, it's not * possible to call release anymore as that calls into the Wayland * connection and the call would fail. This method cleans up the data, so * that the instance can be deleted or set up to a new org_kde_plasma_virtual_desktop interface * once there is a new connection available. * * It is suggested to connect this method to ConnectionThread::connectionDied: * @code * connect(connection, &ConnectionThread::connectionDied, plasmavirtualdesktop, &PlasmaVirtualDesktop::destroy); * @endcode * * @see release **/ void destroy(); /** * Requests this desktop to be activated. * The server may or may not decide to consent to the request. */ void requestActivate(); /** * @returns The unique id of this desktop. The format of the id is decided by the compositor */ QString id() const; /** * @returns User readable name for the desktop. */ QString name() const; /** * @returns True if the desktop is the active one. * when this property changes, activated or deactivated will be emitted. * @see activated * @see deactivated */ bool isActive() const; operator org_kde_plasma_virtual_desktop *(); operator org_kde_plasma_virtual_desktop *() const; Q_SIGNALS: /** * TODO: activeChanged(bool)? * Emitted when this desktop has been activated by the server */ void activated(); /** * Emitted when this desktop has been activated by the server */ void deactivated(); /** * This event is sent after all other properties has been * sent after binding to the desktop manager object and after any * other property changes done after that. This allows * changes to the org_kde_plasma_virtual_desktop properties * to be seen as atomic, even if they happen via multiple events. */ void done(); /** * This virtual desktop has just been removed by the server: * This object itself is about to be deleted. All windows will * lose the association to this desktop. */ void removed(); private: friend class PlasmaVirtualDesktopManagement; explicit PlasmaVirtualDesktop(QObject *parent = nullptr); class Private; QScopedPointer d; }; } } #endif