xbmc/settings/SettingsBase.h

   1 /*
   2  *  Copyright (C) 2016-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 #include "settings/lib/ISettingCallback.h"
  12 #include "threads/CriticalSection.h"
  13
  14 #include <set>
  15 #include <string>
  16 #include <vector>
  17
  18 class CSetting;
  19 class CSettingSection;
  20 class CSettingsManager;
  21 class CVariant;
  22 class CXBMCTinyXML;
  23 class TiXmlElement;
  24
  25 /*!
  26  \brief Basic wrapper around CSettingsManager providing the framework for
  27  properly setting up the settings manager and registering all the callbacks,
  28  handlers and custom setting types.
  29  \sa CSettingsManager
  30  */
  31 class CSettingsBase
  32 {
  33 public:
  34   virtual ~CSettingsBase();
  35
  36   CSettingsManager* GetSettingsManager() const { return m_settingsManager; }
  37
  38   /*!
  39    \brief Initializes the setting system with the generic
  40    settings definition and platform specific setting definitions.
  41
  42    \return True if the initialization was successful, false otherwise
  43    */
  44   virtual bool Initialize();
  45   /*!
  46    \brief Returns whether the settings system has been initialized or not.
  47   */
  48   virtual bool IsInitialized() const;
  49   /*!
  50    \brief Loads the setting values.
  51
  52    \return True if the setting values are successfully loaded, false otherwise
  53    */
  54   virtual bool Load() = 0;
  55   /*!
  56    \brief Tells the settings system that all setting values
  57    have been loaded.
  58
  59    This manual trigger is necessary to enable the ISettingCallback methods
  60    being executed.
  61    */
  62   virtual void SetLoaded();
  63   /*!
  64    \brief Returns whether the settings system has been loaded or not.
  65    */
  66   virtual bool IsLoaded() const;
  67   /*!
  68    \brief Saves the setting values.
  69
  70    \return True if the setting values were successfully saved, false otherwise
  71    */
  72   virtual bool Save() = 0;
  73   /*!
  74    \brief Unloads the previously loaded setting values.
  75
  76    The values of all the settings are reset to their default values.
  77    */
  78   virtual void Unload();
  79   /*!
  80    \brief Uninitializes the settings system.
  81
  82    Unregisters all previously registered callbacks and destroys all setting
  83    objects.
  84    */
  85   virtual void Uninitialize();
  86
  87   /*!
  88    \brief Registers the given ISettingCallback implementation for the given
  89    set of settings.
  90
  91    \param callback ISettingCallback implementation
  92    \param settingList List of setting identifiers for which the given callback shall be triggered
  93    */
  94   void RegisterCallback(ISettingCallback* callback, const std::set<std::string>& settingList);
  95   /*!
  96    \brief Unregisters the given ISettingCallback implementation.
  97
  98    \param callback ISettingCallback implementation
  99    */
 100   void UnregisterCallback(ISettingCallback* callback);
 101
 102   /*!
 103    \brief Gets the setting with the given identifier.
 104
 105    \param id Setting identifier
 106    \return Setting object with the given identifier or NULL if the identifier is unknown
 107    */
 108   std::shared_ptr<CSetting> GetSetting(const std::string& id) const;
 109   /*!
 110    \brief Gets the full list of setting sections.
 111
 112    \return List of setting sections
 113    */
 114   std::vector<std::shared_ptr<CSettingSection>> GetSections() const;
 115   /*!
 116    \brief Gets the setting section with the given identifier.
 117
 118    \param section Setting section identifier
 119    \return Setting section with the given identifier or NULL if the identifier is unknown
 120    */
 121   std::shared_ptr<CSettingSection> GetSection(const std::string& section) const;
 122
 123   /*!
 124    \brief Gets the boolean value of the setting with the given identifier.
 125
 126    \param id Setting identifier
 127    \return Boolean value of the setting with the given identifier
 128    */
 129   bool GetBool(const std::string& id) const;
 130   /*!
 131    \brief Gets the integer value of the setting with the given identifier.
 132
 133    \param id Setting identifier
 134    \return Integer value of the setting with the given identifier
 135    */
 136   int GetInt(const std::string& id) const;
 137   /*!
 138    \brief Gets the real number value of the setting with the given identifier.
 139
 140    \param id Setting identifier
 141    \return Real number value of the setting with the given identifier
 142    */
 143   double GetNumber(const std::string& id) const;
 144   /*!
 145    \brief Gets the string value of the setting with the given identifier.
 146
 147    \param id Setting identifier
 148    \return String value of the setting with the given identifier
 149    */
 150   std::string GetString(const std::string& id) const;
 151   /*!
 152    \brief Gets the values of the list setting with the given identifier.
 153
 154    \param id Setting identifier
 155    \return List of values of the setting with the given identifier
 156    */
 157   std::vector<CVariant> GetList(const std::string& id) const;
 158
 159   /*!
 160    \brief Sets the boolean value of the setting with the given identifier.
 161
 162    \param id Setting identifier
 163    \param value Boolean value to set
 164    \return True if setting the value was successful, false otherwise
 165    */
 166   bool SetBool(const std::string& id, bool value);
 167   /*!
 168    \brief Toggles the boolean value of the setting with the given identifier.
 169
 170    \param id Setting identifier
 171    \return True if toggling the boolean value was successful, false otherwise
 172    */
 173   bool ToggleBool(const std::string& id);
 174   /*!
 175    \brief Sets the integer value of the setting with the given identifier.
 176
 177    \param id Setting identifier
 178    \param value Integer value to set
 179    \return True if setting the value was successful, false otherwise
 180    */
 181   bool SetInt(const std::string& id, int value);
 182   /*!
 183    \brief Sets the real number value of the setting with the given identifier.
 184
 185    \param id Setting identifier
 186    \param value Real number value to set
 187    \return True if setting the value was successful, false otherwise
 188    */
 189   bool SetNumber(const std::string& id, double value);
 190   /*!
 191    \brief Sets the string value of the setting with the given identifier.
 192
 193    \param id Setting identifier
 194    \param value String value to set
 195    \return True if setting the value was successful, false otherwise
 196    */
 197   bool SetString(const std::string& id, const std::string& value);
 198   /*!
 199    \brief Sets the values of the list setting with the given identifier.
 200
 201    \param id Setting identifier
 202    \param value Values to set
 203    \return True if setting the values was successful, false otherwise
 204    */
 205   bool SetList(const std::string& id, const std::vector<CVariant>& value);
 206
 207   /*!
 208   \brief Sets the value of the setting with the given identifier to its default.
 209
 210   \param id Setting identifier
 211   \return True if setting the value to its default was successful, false otherwise
 212   */
 213   bool SetDefault(const std::string &id);
 214   /*!
 215   \brief Sets the value of all settings to their default.
 216   */
 217   void SetDefaults();
 218
 219 protected:
 220   CSettingsBase();
 221
 222   virtual void InitializeSettingTypes() { }
 223   virtual void InitializeControls() { }
 224   virtual void InitializeOptionFillers() { }
 225   virtual void UninitializeOptionFillers() { }
 226   virtual void InitializeConditions() { }
 227   virtual void UninitializeConditions() { }
 228   virtual bool InitializeDefinitions() = 0;
 229   virtual void InitializeVisibility() { }
 230   virtual void InitializeDefaults() { }
 231   virtual void InitializeISettingsHandlers() { }
 232   virtual void UninitializeISettingsHandlers() { }
 233   virtual void InitializeISubSettings() { }
 234   virtual void UninitializeISubSettings() { }
 235   virtual void InitializeISettingCallbacks() { }
 236   virtual void UninitializeISettingCallbacks() { }
 237
 238   bool InitializeDefinitionsFromXml(const CXBMCTinyXML& xml);
 239
 240   /*!
 241   \brief Loads setting values from the given document in XML format
 242
 243   \param xml Document in XML format from which the settings are loaded
 244   \param updated Output parameter indicating whether setting values had to be updated
 245   \return True if the setting values were successfully loaded, false otherwise
 246   */
 247   bool LoadValuesFromXml(const CXBMCTinyXML& xml, bool& updated);
 248   /*!
 249   \brief Saves the setting values in XML format to the given document.
 250
 251   \param xml Document to save the setting values in XML format into
 252   \return True if the setting values were successfully saved, false otherwise
 253   */
 254   bool SaveValuesToXml(CXBMCTinyXML& xml) const;
 255
 256   /*!
 257   \brief Loads setting values from the given XML element.
 258
 259   \param root XML element containing setting values
 260   \param updated Output parameter indicating whether setting values had to be updated
 261   \return True if the setting values were successfully loaded, false otherwise
 262   */
 263   bool LoadValuesFromXml(const TiXmlElement* root, bool& updated);
 264
 265   /*!
 266   \brief Loads hidden setting values from the given XML element.
 267
 268   \param root XML element containing setting values
 269   \return True if the setting values were successfully loaded, false otherwise
 270   */
 271   bool LoadHiddenValuesFromXml(const TiXmlElement* root);
 272
 273   bool m_initialized = false;
 274   CSettingsManager* m_settingsManager;
 275   mutable CCriticalSection m_critical;
 276 private:
 277   CSettingsBase(const CSettingsBase&) = delete;
 278   CSettingsBase& operator=(const CSettingsBase&) = delete;
 279 };