Differential D8396 Diff 22482 src/client/idleinhibit.h

Changeset View

Standalone View

src/client/idleinhibit.h

This file was added.

		1		/****************************************************************************
		2		Copyright 2017 Martin Flöser <mgraesslin@kde.org>
		3
		4		This library is free software; you can redistribute it and/or
		5		modify it under the terms of the GNU Lesser General Public
		6		License as published by the Free Software Foundation; either
		7		version 2.1 of the License, or (at your option) version 3, or any
		8		later version accepted by the membership of KDE e.V. (or its
		9		successor approved by the membership of KDE e.V.), which shall
		10		act as a proxy defined in Section 6 of version 3 of the license.
		11
		12		This library is distributed in the hope that it will be useful,
		13		but WITHOUT ANY WARRANTY; without even the implied warranty of
		14		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
		15		Lesser General Public License for more details.
		16
		17		You should have received a copy of the GNU Lesser General Public
		18		License along with this library. If not, see <http://www.gnu.org/licenses/>.
		19		****************************************************************************/
		20		#ifndef KWAYLAND_CLIENT_IDLEINHIBIT_H
		21		#define KWAYLAND_CLIENT_IDLEINHIBIT_H
		22
		23		#include <QObject>
		24
		25		#include <KWayland/Client/kwaylandclient_export.h>
		26
		27		struct zwp_idle_inhibit_manager_v1;
		28		struct zwp_idle_inhibitor_v1;
		29
		30		namespace KWayland
		31		{
		32		namespace Client
		33		{
		34
		35		class EventQueue;
		36		class Surface;
		37		class IdleInhibitor;
		38
		39		/**
		40		* @short Wrapper for the zwp_idle_inhibit_manager_v1 interface.
		41		*
		42		* This class provides a convenient wrapper for the zwp_idle_inhibit_manager_v1 interface.
		43		*
		44		* To use this class one needs to interact with the Registry. There are two
		45		* possible ways to create the IdleInhibitManager interface:
		46		* @code
		47		* IdleInhibitManager *c = registry->createIdleInhibitManager(name, version);
		48		* @endcode
		49		*
		50		* This creates the IdleInhibitManager and sets it up directly. As an alternative this
		51		* can also be done in a more low level way:
		52		* @code
		53		* IdleInhibitManager *c = new IdleInhibitManager;
		54		* c->setup(registry->bindIdleInhibitManager(name, version));
		55		* @endcode
		56		*
		57		* The IdleInhibitManager can be used as a drop-in replacement for any zwp_idle_inhibit_manager_v1
		58		* pointer as it provides matching cast operators.
		59		*
		60		* @see Registry
		61		* @since 5.41
		62		**/
		63		class KWAYLANDCLIENT_EXPORT IdleInhibitManager : public QObject
		64		{
		65		Q_OBJECT
		66		public:
		67		/**
		68		* Creates a new IdleInhibitManager.
		69		* Note: after constructing the IdleInhibitManager it is not yet valid and one needs
		70		* to call setup. In order to get a ready to use IdleInhibitManager prefer using
		71		* Registry::createIdleInhibitManager.
		72		**/
		73		explicit IdleInhibitManager(QObject *parent = nullptr);
		74		virtual ~IdleInhibitManager();
		75
		76		/**
		77		* Setup this IdleInhibitManager to manage the @p idleinhibitmanager.
		78		* When using Registry::createIdleInhibitManager there is no need to call this
		79		* method.
		80		**/
		81		void setup(zwp_idle_inhibit_manager_v1 *idleinhibitmanager);
		82		/**
		83		* @returns @c true if managing a zwp_idle_inhibit_manager_v1.
		84		**/
		85		bool isValid() const;
		86		/**
		87		* Releases the zwp_idle_inhibit_manager_v1 interface.
		88		* After the interface has been released the IdleInhibitManager instance is no
		89		* longer valid and can be setup with another zwp_idle_inhibit_manager_v1 interface.
		90		**/
		91		void release();
		92		/**
		93		* Destroys the data held by this IdleInhibitManager.
		94		* This method is supposed to be used when the connection to the Wayland
		95		* server goes away. If the connection is not valid anymore, it's not
		96		* possible to call release anymore as that calls into the Wayland
		97		* connection and the call would fail. This method cleans up the data, so
		98		* that the instance can be deleted or set up to a new zwp_idle_inhibit_manager_v1 interface
		99		* once there is a new connection available.
		100		*
		101		* It is suggested to connect this method to ConnectionThread::connectionDied:
		102		* @code
		103		* connect(connection, &ConnectionThread::connectionDied, idleinhibitmanager, &IdleInhibitManager::destroy);
		104		* @endcode
		105		*
		106		* @see release
		107		**/
		108		void destroy();
		109
		110		/**
		111		* Sets the @p queue to use for creating objects with this IdleInhibitManager.
		112		**/
		113		void setEventQueue(EventQueue *queue);
		114		/**
		115		* @returns The event queue to use for creating objects with this IdleInhibitManager.
		116		**/
		117		EventQueue *eventQueue();
		118
		119		/**
		120		* Creates an IdleInhibitor for the given @p surface.
		121		* While the IdleInhibitor exists the @p surface is marked to inhibit idle.
		122		* @param surface The Surface which should have idle inhibited
		123		* @param parent The parent object for the IdleInhibitor
		124		* @returns The created IdleInhibitor
		125		**/
		126		IdleInhibitor createInhibitor(Surface surface, QObject *parent = nullptr);
		127
		128		operator zwp_idle_inhibit_manager_v1*();
		129		operator zwp_idle_inhibit_manager_v1*() const;
		130
		131		Q_SIGNALS:
		132		/**
		133		* The corresponding global for this interface on the Registry got removed.
		134		*
		135		* This signal gets only emitted if the IdleInhibitManager got created by
		136		* Registry::createIdleInhibitManager
		137		**/
		138		void removed();
		139
		140		private:
		141		class Private;
		142		QScopedPointer<Private> d;
		143		};
		144
		145		/**
		146		* An IdleInhibitor prevents the Output that the associated Surface is visible on from being
		147		* set to a state where it is not visually usable due to lack of user interaction
		148		* (e.g. blanked, dimmed, locked, set to power save, etc.) Any screensaver processes are
		149		* also blocked from displaying.
		150		*
		151		* If the Surface is destroyed, unmapped, becomes occluded, loses visibility, or otherwise
		152		* becomes not visually relevant for the user, the IdleInhibitor will not be honored by
		153		* the compositor; if the Surface subsequently regains visibility the inhibitor takes effect
		154		* once again.
		155		* Likewise, the IdleInhibitor isn't honored if the system was already idled at the time the
		156		* IdleInhibitor was established, although if the system later de-idles and re-idles the
		157		* IdleInhibitor will take effect.
		158		*
		159		* @see IdleInhibitManager
		160		* @see Surface
		161		* @since 5.41
		162		**/
		163		class KWAYLANDCLIENT_EXPORT IdleInhibitor : public QObject
		164		{
		165		Q_OBJECT
		166		public:
		167		virtual ~IdleInhibitor();
		168
		169		/**
		170		* Setup this IdleInhibitor to manage the @p idleinhibitor.
		171		* When using IdleInhibitManager::createIdleInhibitor there is no need to call this
		172		* method.
		173		**/
		174		void setup(zwp_idle_inhibitor_v1 *idleinhibitor);
		175		/**
		176		* @returns @c true if managing a zwp_idle_inhibitor_v1.
		177		**/
		178		bool isValid() const;
		179		/**
		180		* Releases the zwp_idle_inhibitor_v1 interface.
		181		* After the interface has been released the IdleInhibitor instance is no
		182		* longer valid and can be setup with another zwp_idle_inhibitor_v1 interface.
		183		**/
		184		void release();
		185		/**
		186		* Destroys the data held by this IdleInhibitor.
		187		* This method is supposed to be used when the connection to the Wayland
		188		* server goes away. If the connection is not valid anymore, it's not
		189		* possible to call release anymore as that calls into the Wayland
		190		* connection and the call would fail. This method cleans up the data, so
		191		* that the instance can be deleted or set up to a new zwp_idle_inhibitor_v1 interface
		192		* once there is a new connection available.
		193		*
		194		* It is suggested to connect this method to ConnectionThread::connectionDied:
		195		* @code
		196		* connect(connection, &ConnectionThread::connectionDied, idleinhibitor, &IdleInhibitor::destroy);
		197		* @endcode
		198		*
		199		* @see release
		200		**/
		201		void destroy();
		202
		203		operator zwp_idle_inhibitor_v1*();
		204		operator zwp_idle_inhibitor_v1*() const;
		205
		206		private:
		207		friend class IdleInhibitManager;
		208		explicit IdleInhibitor(QObject *parent = nullptr);
		209		class Private;
		210		QScopedPointer<Private> d;
		211		};
		212
		213
		214		}
		215		}
		216
		217		#endif