File indexing completed on 2024-05-19 04:03:21

0001 /*
0002     SPDX-FileCopyrightText: 2014 Alejandro Fiestas Olivares <afiestas@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0005 */
0006 
0007 #ifndef SOLID_POWER_H
0008 #define SOLID_POWER_H
0009 
0010 #include "solid_export.h"
0011 #include <QObject>
0012 
0013 namespace Solid
0014 {
0015 class StatesJob;
0016 class AcPluggedJob;
0017 class InhibitionJob;
0018 class RequestStateJob;
0019 class SOLID_EXPORT Power : public QObject
0020 {
0021     Q_OBJECT
0022 public:
0023     /**
0024      * List of states a device can be in
0025      *
0026      * This list of states can be used to either put the device
0027      * running the code into a specific state (for example put a
0028      * laptop to sleep) or to avoid (inhibit) that state to happen,
0029      * for example to prevent the screen to be dimed automatically
0030      *
0031      * Since this is quite specific to each platform some backends might
0032      * not support all states.
0033      *
0034      * Some States are more complex or contain sub-states, those are usually
0035      * set using a specific job (for example Sleep can be done either using suspend to ram,
0036      * suspend to disk or an hybrid approach).
0037      *
0038      * @see InhibitionTypes
0039      */
0040     enum InhibitionType {
0041         None = 0,
0042         Sleep = 1 << 0,
0043         Screen = 1 << 1,
0044         Shutdown = 1 << 3,
0045     };
0046     /*
0047      * Stores a combination of #InhibitionType values.
0048      */
0049     Q_DECLARE_FLAGS(InhibitionTypes, InhibitionType)
0050     Q_FLAG(InhibitionTypes)
0051     /**
0052      * Returns an instance of Power
0053      *
0054      * Having an instance of Power is useful to monitor any changes
0055      * in the power management system by connecting to its signals, like
0056      * acPluggedChanged().
0057      *
0058      * If you are interested in Power during the entire life cycle of your
0059      * application, then you want to use this singleton. If instead you are
0060      * only interested for a short period of time, consider instantiating your own
0061      * Solid::Power so you can free the memory at any point.
0062      */
0063     static Power *self();
0064 
0065     /**
0066      * Returns an AcPluggedJob
0067      *
0068      * The returned AcPluggedJob has to be started, when finished
0069      * the Job::result() signal will be emitted.
0070      */
0071     static AcPluggedJob *isAcPlugged(QObject *parent = nullptr);
0072 
0073     /**
0074      * Returns an InhibitionJob
0075      *
0076      * The returned job is initialized with the given @p states and @p description
0077      */
0078     static InhibitionJob *inhibit(Power::InhibitionTypes states, const QString &description, QObject *parent = nullptr);
0079 
0080     /**
0081      * Query the supported states (like Sleep or Hibernation)
0082      * @return a StatesJob
0083      */
0084     static StatesJob *supportedStates(QObject *parent = nullptr);
0085 
0086     /**
0087      * Set the computer in a desired @p state (like Sleep or Hibernation)
0088      * @return a RequestStateJob
0089      */
0090     static RequestStateJob *requestState(Power::InhibitionType state, QObject *parent = nullptr);
0091 
0092     /**
0093      * If you are not going to destroy this object for the entire
0094      * application life cycle, you might want to use self() singleton.
0095      *
0096      * The only reason to instantiate your own Power object is for when an
0097      * application is only interested in power management during a small
0098      * period of time and you want to free the memory after using it.
0099      */
0100     explicit Power(QObject *parent = nullptr);
0101 
0102 Q_SIGNALS:
0103     /**
0104      * Emitted when the system changes the power source
0105      * @param plugged whether the system runs on AC
0106      */
0107     void acPluggedChanged(bool plugged);
0108 
0109     /**
0110      * Emitted when the system is about to suspend/hibernate
0111      *
0112      * @since 5.6
0113      */
0114     void aboutToSuspend();
0115 
0116     /**
0117      * Emitted when the system has just resumed from being suspended/hibernated
0118      */
0119     void resumeFromSuspend();
0120 
0121 private:
0122     class Private;
0123     Private *const d;
0124 };
0125 
0126 Q_DECLARE_OPERATORS_FOR_FLAGS(Power::InhibitionTypes)
0127 
0128 }
0129 
0130 #endif // SOLID_POWER_H