From 27e53990ed7100159cc08fd8470a9faecd011cbe Mon Sep 17 00:00:00 2001 From: lat9nq <22451773+lat9nq@users.noreply.github.com> Date: Tue, 13 Jun 2023 19:37:54 -0400 Subject: [PATCH] settings: Document BasicSetting, add Ranged --- src/common/settings_common.h | 119 ++++++++++++++++++++++++++++++---- src/common/settings_setting.h | 4 ++ 2 files changed, 112 insertions(+), 11 deletions(-) diff --git a/src/common/settings_common.h b/src/common/settings_common.h index 9d1044a19..4d6d3021e 100644 --- a/src/common/settings_common.h +++ b/src/common/settings_common.h @@ -57,6 +57,10 @@ public: u32 count; }; +/** + * BasicSetting is an abstract class that only keeps track of metadata. The string methods are + * available to get data values out. + */ class BasicSetting { protected: explicit BasicSetting(Linkage& linkage, const std::string& name, enum Category category_, @@ -65,45 +69,117 @@ protected: public: virtual ~BasicSetting(); - /* Data retrieval */ + /* + * Data retrieval + */ + /** + * Returns a string representation of the internal data. If the Setting is Switchable, it + * respects the internal global state: it is based on GetValue(). + * + * @returns A string representation of the internal data. + */ [[nodiscard]] virtual std::string ToString() const = 0; + + /** + * Returns a string representation of the global version of internal data. If the Setting is + * not Switchable, it behaves like ToString. + * + * @returns A string representation of the global version of internal data. + */ [[nodiscard]] virtual std::string ToStringGlobal() const; + + /** + * @returns A string representation of the Setting's default value. + */ [[nodiscard]] virtual std::string DefaultToString() const = 0; + + /** + * Returns a string representation of the minimum value of the setting. If the Setting is not + * ranged, the string represents the default initialization of the data type. + * + * @returns A string representation of the minimum value of the setting. + */ [[nodiscard]] virtual std::string MinVal() const = 0; + + /** + * Returns a string representation of the maximum value of the setting. If the Setting is not + * ranged, the string represents the default initialization of the data type. + * + * @returns A string representation of the maximum value of the setting. + */ [[nodiscard]] virtual std::string MaxVal() const = 0; + + /** + * Takes a string input, converts it to the internal data type if necessary, and then runs + * SetValue with it. + * + * @param load String of the input data. + */ virtual void LoadString(const std::string& load) = 0; + + /** + * Returns a string representation of the data. If the data is an enum, it returns a string of + * the enum value. If the internal data type is not an enum, this is equivalent to ToString. + * + * e.g. renderer_backend.Canonicalize() == "OpenGL" + * + * @returns Canonicalized string representation of the internal data + */ [[nodiscard]] virtual std::string Canonicalize() const = 0; - /* Identification */ + /* + * Metadata + */ - [[nodiscard]] virtual std::type_index TypeId() const = 0; - [[nodiscard]] virtual constexpr bool IsEnum() const = 0; /** - * Returns whether the current setting is Switchable. + * @returns A unique identifier for the Setting's internal data type. + */ + [[nodiscard]] virtual std::type_index TypeId() const = 0; + + /** + * Returns true if the Setting's internal data type is an enum. + * + * @returns True if the Setting's internal data type is an enum + */ + [[nodiscard]] virtual constexpr bool IsEnum() const = 0; + + /** + * Returns true if the current setting is Switchable. * * @returns If the setting is a SwitchableSetting */ [[nodiscard]] virtual constexpr bool Switchable() const { return false; } + /** - * Returns the save preference of the setting i.e. when saving or reading the setting from a - * frontend, whether this setting should be skipped. + * Returns true to suggest that a frontend can read or write the setting to a configuration + * file. * * @returns The save preference */ [[nodiscard]] bool Save() const; + + /** + * @returns true if the current setting can be changed while the guest is running. + */ [[nodiscard]] bool RuntimeModfiable() const; + + /** + * @returns A unique number corresponding to the setting. + */ [[nodiscard]] constexpr u32 Id() const { return id; } + /** * Returns the setting's category AKA INI group. * * @returns The setting's category */ [[nodiscard]] Category Category() const; + /** * Returns the label this setting was created with. * @@ -111,17 +187,38 @@ public: */ [[nodiscard]] const std::string& GetLabel() const; - /* Switchable settings */ + /** + * @returns If the Setting checks input values for valid ranges. + */ + [[nodiscard]] virtual constexpr bool Ranged() const = 0; + /* + * Switchable settings + */ + + /** + * Sets a setting's global state. True means use the normal setting, false to use a custom + * value. Has no effect if the Setting is not Switchable. + * + * @param global The desired state + */ virtual void SetGlobal(bool global); + + /** + * Returns true if the setting is using the normal setting value. Always true if the setting is + * not Switchable. + * + * @returns The Setting's global state + */ [[nodiscard]] virtual bool UsingGlobal() const; private: const std::string label; ///< The setting's label const enum Category category; ///< The setting's category AKA INI group - const u32 id; - const bool save; - const bool runtime_modifiable; + const u32 id; ///< Unique integer for the setting + const bool save; ///< Suggests if the setting should be saved and read to a frontend config + const bool + runtime_modifiable; ///< Suggests if the setting can be modified while a guest is running }; } // namespace Settings diff --git a/src/common/settings_setting.h b/src/common/settings_setting.h index 1ca3acf18..658b6328d 100644 --- a/src/common/settings_setting.h +++ b/src/common/settings_setting.h @@ -198,6 +198,10 @@ public: return this->ToString(maximum); } + constexpr bool Ranged() const override { + return ranged; + } + protected: Type value{}; ///< The setting const Type default_value{}; ///< The default value