File indexing completed on 2024-04-21 16:17:33

 /*
  *  SPDX-FileCopyrightText: 2012 Alejandro Fiestas Olivares <afiestas@kde.org>
  *  SPDX-FileCopyrightText: 2014 Daniel Vrátil <dvratil@redhat.com>
  *
  *  SPDX-License-Identifier: LGPL-2.1-or-later
  */
 
 #ifndef KSCREEN_CONFIG_H
 #define KSCREEN_CONFIG_H
 
 #include "kscreen_export.h"
 #include "output.h"
 #include "screen.h"
 #include "types.h"
 
 #include <QHash>
 #include <QMetaType>
 #include <QObject>
 
 #include <cstdint>
 #include <optional>
 
 namespace KScreen
 {
 class Output;
 
 /**
  * Represents a (or the) screen configuration.
  *
  * This is the main class of KScreen, with it you can use
  * the static methods current() to get the systems config and
  * setConfig() to apply a config to the system.
  *
  * Also, you can instantiate an empty Config, this is usually done
  * to create a config (with the objective of setting it) from scratch
  * and for example unserialize a saved config to it.
  *
  */
 class KSCREEN_EXPORT Config : public QObject
 {
     Q_OBJECT
     Q_PROPERTY(ScreenPtr screen READ screen)
     Q_PROPERTY(OutputList outputs READ outputs)
 
 public:
     enum class ValidityFlag {
         None = 0x0,
         RequireAtLeastOneEnabledScreen = 0x1,
     };
     Q_ENUM(ValidityFlag)
     Q_DECLARE_FLAGS(ValidityFlags, ValidityFlag)
 
     /** This indicates which features the used backend supports.
      *
      * @see supportedFeatures
      * @since 5.7
      */
     enum class Feature {
         None = 0, ///< None of the mentioned features are supported.
         PrimaryDisplay = 1, ///< The backend knows about the concept of a primary display
         Writable = 1 << 1, ///< The backend supports setting the config, it's not read-only.
         PerOutputScaling = 1 << 2, ///< The backend supports scaling each output individually.
         OutputReplication = 1 << 3, ///< The backend supports replication of outputs.
         AutoRotation = 1 << 4, ///< The backend supports automatic rotation of outputs.
         TabletMode = 1 << 5, ///< The backend supports querying if a device is in tablet mode.
         SynchronousOutputChanges = 1 << 6, ///< The backend supports blocking until the output setting changes are applied
         XwaylandScales = 1 << 7, ///< The backend supports adapting Xwayland clients to a certain scale
     };
     Q_ENUM(Feature)
     Q_DECLARE_FLAGS(Features, Feature)
 
     /**
      * Validates that a config can be applied in the current system
      *
      * Each system has different constrains, this method will test
      * the given config with those constrains to see if it
      * can be applied.
      *
      * @arg config to be checked
      * @flags enable additional optional checks
      * @return true if the configuration can be applied, false if not.
      * @since 5.3.0
      */
     static bool canBeApplied(const ConfigPtr &config, ValidityFlags flags);
 
     /**
      * Validates that a config can be applied in the current system
      *
      * Each system has different constrains, this method will test
      * the given config with those constrains to see if it
      * can be applied.
      *
      * @arg config to be checked
      * @return true if the configuration can be applied, false if not.
      */
     static bool canBeApplied(const ConfigPtr &config);
 
     /**
      * Instantiate an empty config
      *
      * Usually you do not want to use this constructor since there are some
      * values that make no sense to set (for example you want the Screen of
      * the current systme).
      *
      * So usually what you do is call current() and then modify
      * whatever you need.
      */
     explicit Config();
     ~Config() override;
 
     /**
      * Duplicates the config
      *
      * @return a new Config instance with same property values
      */
     ConfigPtr clone() const;
 
     /**
      * Returns an identifying hash for this config in regards to its
      * connected outputs.
      *
      * The hash is calculated with a sorted combination of all
      * connected output hashes.
      *
      * @return sorted hash combination of all connected outputs
      * @since 5.15
      */
     QString connectedOutputsHash() const;
 
     ScreenPtr screen() const;
     void setScreen(const ScreenPtr &screen);
 
     OutputPtr output(int outputId) const;
     OutputList outputs() const;
     OutputList connectedOutputs() const;
 
     /**
      * Find primary output. Primary output is the output with priority 1. May be
      * null.
      */
     OutputPtr primaryOutput() const;
     /**
      * Setting output to be the primary one is equivalent to setting its
      * priority to 1.
      */
     void setPrimaryOutput(const OutputPtr &output);
     /**
      * Add an output to this configuration.
      *
      * This method does not ensure consistency of priorities, it is up to the
      * caller to perform necessary adjustments afterwards. The reason is that it
      * might be used in a loop (such as adding all outputs) where committing
      * intermediate states is undesirable.
      */
     void addOutput(const OutputPtr &output);
     /**
      * Remove an output with matching ID from this configuration.
      *
      * This method does not ensure consistency of priorities, it is up to the
      * caller to perform necessary adjustments afterwards. The reason is that it
      * might be used in a loop (such as removing all outputs) where committing
      * intermediate states is undesirable.
      */
     void removeOutput(int outputId);
     /**
      * Replace all existing outputs with the given ones.
      *
      * Unlike addOutput and removeOutput which operate on individual items
      * presumably in a loop, this method will call adjustPriorities() before
      * returning.
      */
     void setOutputs(const OutputList &outputs);
 
     /**
      * Set output's priority and call adjustPriorities() trying to retain
      * relative ordering of the output. Setting priority to zero with this
      * method will disable the output, otherwise the output will be enabled.
      */
     void setOutputPriority(const OutputPtr &output, uint32_t priority);
 
     void setOutputPriorities(QMap<OutputPtr, uint32_t> &priorities);
 
     /**
      * Ensure consistency and continuity of priorities.
      *
      * Most methods operating on outputs are doing so in loop, where committing
      * intermediate states is undesirable. This method restores the balance by
      * settings priority of all disabled outputs to 0, disabling all outputs
      * whose priority is 0 (i.e. it works in both directions), and sorting all
      * the remaining ones, such that they are numbered strictly sequentially
      * starting from 1.
      * @param keep The output, which priority should stay as close as possible
      * to its current one. It is not possible to guarantee, but the algorithm
      * will do its best to prioritize this output among others, if there happens
      * to be multiple ones with the same priority number.
      */
     void adjustPriorities(std::optional<OutputPtr> keep = std::nullopt);
 
     bool isValid() const;
     void setValid(bool valid);
 
     void apply(const ConfigPtr &other);
 
     /** Indicates features supported by the backend. This exists to allow the user
      * to find out which of the features offered by libkscreen are actually supported
      * by the backend. Not all backends are writable (QScreen, for example is
      * read-only, only XRandR, but not KWayland support the primary display, etc.).
      *
      * @return Flags for features that are supported for this config, determined by
      * the backend.
      * @see setSupportedFeatures
      * @since 5.7
      */
     Features supportedFeatures() const;
 
     /** Sets the features supported by this backend. This should not be called by the
      * user, but by the backend.
      *
      * @see supportedFeatures
      * @since 5.7
      */
     void setSupportedFeatures(const Features &features);
 
     /**
      * Indicates that the device supports switching between a default and a tablet mode. This is
      * common for convertibles.
      *
      * @return true when tablet mode is available, otherwise false
      * @see setTabletModeAvailable
      * @since 5.18
      */
     bool tabletModeAvailable() const;
 
     /** Sets if the device supports a tablet mode. This should not be called by the
      * user, but by the backend.
      *
      * @see tabletModeAvailable
      * @since 5.18
      */
     void setTabletModeAvailable(bool available);
 
     /**
      * Indicates that the device is currently in tablet mode.
      *
      * @return true when in tablet mode, otherwise false
      * @see setTabletModeEngaged
      * @since 5.18
      */
     bool tabletModeEngaged() const;
 
     /**
      * Sets if the device is currently in tablet mode. This should not be called by the
      * user, but by the backend.
      *
      * @see tabletModeEngaged
      * @since 5.18
      */
     void setTabletModeEngaged(bool engaged);
 
     QRect outputGeometryForOutput(const KScreen::Output &output) const;
 
     QSizeF logicalSizeForOutput(const KScreen::Output &output) const;
 
 Q_SIGNALS:
     void outputAdded(const KScreen::OutputPtr &output);
     void outputRemoved(int outputId);
     void prioritiesChanged();
 
 private:
     Q_DISABLE_COPY(Config)
 
     class Private;
     Private *const d;
 };
 
 } // KScreen namespace
 
 Q_DECLARE_OPERATORS_FOR_FLAGS(KScreen::Config::Features)
 
 KSCREEN_EXPORT QDebug operator<<(QDebug dbg, const KScreen::ConfigPtr &config);
 
 #endif // KSCREEN_CONFIG_H