xbmc/interfaces/legacy/Settings.h

   1 /*
   2  *  Copyright (C) 2017-2021 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 "commons/Exception.h"
  12 #include "interfaces/legacy/AddonClass.h"
  13 #include "interfaces/legacy/AddonString.h"
  14 #include "interfaces/legacy/Exception.h"
  15 #include "interfaces/legacy/Tuple.h"
  16 #include "settings/lib/SettingDefinitions.h"
  17
  18 #include <memory>
  19 #include <string>
  20 #include <vector>
  21
  22 class CSettingsBase;
  23
  24 namespace XBMCAddon
  25 {
  26 namespace xbmcaddon
  27 {
  28
  29 XBMCCOMMONS_STANDARD_EXCEPTION(SettingCallbacksNotSupportedException);
  30
  31 //
  32 /// \defgroup python_settings Settings
  33 /// \ingroup python_xbmcaddon
  34 /// @{
  35 /// @brief **Add-on settings**
  36 ///
  37 /// \python_class{ Settings() }
  38 ///
  39 /// This wrapper provides access to the settings specific to an add-on.
  40 /// It supports reading and writing specific setting values.
  41 ///
  42 ///-----------------------------------------------------------------------
  43 /// @python_v20 New class added.
  44 ///
  45 /// **Example:**
  46 /// ~~~~~~~~~~~~~{.py}
  47 /// ...
  48 /// settings = xbmcaddon.Addon('id').getSettings()
  49 /// ...
  50 /// ~~~~~~~~~~~~~
  51 //
  52 class Settings : public AddonClass
  53 {
  54 public:
  55 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  56 #ifndef SWIG
  57   std::shared_ptr<CSettingsBase> settings;
  58   Settings(std::shared_ptr<CSettingsBase> settings);
  59 #endif
  60   virtual ~Settings() = default;
  61 #endif
  62
  63 #ifdef DOXYGEN_SHOULD_USE_THIS
  64   ///
  65   /// \ingroup python_settings
  66   /// @brief \python_func{ getBool(id) }
  67   /// Returns the value of a setting as a boolean.
  68   ///
  69   /// @param id                     string - id of the setting that the module needs to access.
  70   /// @return                       bool - Setting as a boolean
  71   ///
  72   ///
  73   ///-----------------------------------------------------------------------
  74   /// @python_v20 New function added.
  75   ///
  76   /// **Example:**
  77   /// ~~~~~~~~~~~~~{.py}
  78   /// ..
  79   /// enabled = settings.getBool('enabled')
  80   /// ..
  81   /// ~~~~~~~~~~~~~
  82   ///
  83   getBool(...);
  84 #else
  85   bool getBool(const char* id);
  86 #endif
  87
  88 #ifdef DOXYGEN_SHOULD_USE_THIS
  89   ///
  90   /// \ingroup python_settings
  91   /// @brief \python_func{ getInt(id) }
  92   /// Returns the value of a setting as an integer.
  93   ///
  94   /// @param id                     string - id of the setting that the module needs to access.
  95   /// @return                       integer - Setting as an integer
  96   ///
  97   ///
  98   ///-----------------------------------------------------------------------
  99   /// @python_v20 New function added.
 100   ///
 101   /// **Example:**
 102   /// ~~~~~~~~~~~~~{.py}
 103   /// ..
 104   /// max = settings.getInt('max')
 105   /// ..
 106   /// ~~~~~~~~~~~~~
 107   ///
 108   getInt(...);
 109 #else
 110   int getInt(const char* id);
 111 #endif
 112
 113 #ifdef DOXYGEN_SHOULD_USE_THIS
 114   ///
 115   /// \ingroup python_settings
 116   /// @brief \python_func{ getNumber(id) }
 117   /// Returns the value of a setting as a floating point number.
 118   ///
 119   /// @param id                     string - id of the setting that the module needs to access.
 120   /// @return                       float - Setting as a floating point number
 121   ///
 122   ///
 123   ///-----------------------------------------------------------------------
 124   /// @python_v20 New function added.
 125   ///
 126   /// **Example:**
 127   /// ~~~~~~~~~~~~~{.py}
 128   /// ..
 129   /// max = settings.getNumber('max')
 130   /// ..
 131   /// ~~~~~~~~~~~~~
 132   ///
 133   getNumber(...);
 134 #else
 135   double getNumber(const char* id);
 136 #endif
 137
 138 #ifdef DOXYGEN_SHOULD_USE_THIS
 139   ///
 140   /// \ingroup python_settings
 141   /// @brief \python_func{ getString(id) }
 142   /// Returns the value of a setting as a unicode string.
 143   ///
 144   /// @param id                     string - id of the setting that the module needs to access.
 145   /// @return                       string - Setting as a unicode string
 146   ///
 147   ///
 148   ///-----------------------------------------------------------------------
 149   /// @python_v20 New function added.
 150   ///
 151   /// **Example:**
 152   /// ~~~~~~~~~~~~~{.py}
 153   /// ..
 154   /// apikey = settings.getString('apikey')
 155   /// ..
 156   /// ~~~~~~~~~~~~~
 157   ///
 158   getString(...);
 159 #else
 160   String getString(const char* id);
 161 #endif
 162
 163 #ifdef DOXYGEN_SHOULD_USE_THIS
 164   ///
 165   /// \ingroup python_settings
 166   /// @brief \python_func{ getBoolList(id) }
 167   /// Returns the value of a setting as a list of booleans.
 168   ///
 169   /// @param id                     string - id of the setting that the module needs to access.
 170   /// @return                       list - Setting as a list of booleans
 171   ///
 172   ///
 173   ///-----------------------------------------------------------------------
 174   /// @python_v20 New function added.
 175   ///
 176   /// **Example:**
 177   /// ~~~~~~~~~~~~~{.py}
 178   /// ..
 179   /// enabled = settings.getBoolList('enabled')
 180   /// ..
 181   /// ~~~~~~~~~~~~~
 182   ///
 183   getBoolList(...);
 184 #else
 185   std::vector<bool> getBoolList(const char* id);
 186 #endif
 187
 188 #ifdef DOXYGEN_SHOULD_USE_THIS
 189   ///
 190   /// \ingroup python_settings
 191   /// @brief \python_func{ getIntList(id) }
 192   /// Returns the value of a setting as a list of integers.
 193   ///
 194   /// @param id                     string - id of the setting that the module needs to access.
 195   /// @return                       list - Setting as a list of integers
 196   ///
 197   ///
 198   ///-----------------------------------------------------------------------
 199   /// @python_v20 New function added.
 200   ///
 201   /// **Example:**
 202   /// ~~~~~~~~~~~~~{.py}
 203   /// ..
 204   /// ids = settings.getIntList('ids')
 205   /// ..
 206   /// ~~~~~~~~~~~~~
 207   ///
 208   getIntList(...);
 209 #else
 210   std::vector<int> getIntList(const char* id);
 211 #endif
 212
 213 #ifdef DOXYGEN_SHOULD_USE_THIS
 214   ///
 215   /// \ingroup python_settings
 216   /// @brief \python_func{ getNumberList(id) }
 217   /// Returns the value of a setting as a list of floating point numbers.
 218   ///
 219   /// @param id                     string - id of the setting that the module needs to access.
 220   /// @return                       list - Setting as a list of floating point numbers
 221   ///
 222   ///
 223   ///-----------------------------------------------------------------------
 224   /// @python_v20 New function added.
 225   ///
 226   /// **Example:**
 227   /// ~~~~~~~~~~~~~{.py}
 228   /// ..
 229   /// max = settings.getNumberList('max')
 230   /// ..
 231   /// ~~~~~~~~~~~~~
 232   ///
 233   getNumberList(...);
 234 #else
 235   std::vector<double> getNumberList(const char* id);
 236 #endif
 237
 238 #ifdef DOXYGEN_SHOULD_USE_THIS
 239   ///
 240   /// \ingroup python_settings
 241   /// @brief \python_func{ getStringList(id) }
 242   /// Returns the value of a setting as a list of unicode strings.
 243   ///
 244   /// @param id                     string - id of the setting that the module needs to access.
 245   /// @return                       list - Setting as a list of unicode strings
 246   ///
 247   ///
 248   ///-----------------------------------------------------------------------
 249   /// @python_v20 New function added.
 250   ///
 251   /// **Example:**
 252   /// ~~~~~~~~~~~~~{.py}
 253   /// ..
 254   /// views = settings.getStringList('views')
 255   /// ..
 256   /// ~~~~~~~~~~~~~
 257   ///
 258   getStringList(...);
 259 #else
 260   std::vector<String> getStringList(const char* id);
 261 #endif
 262
 263 #ifdef DOXYGEN_SHOULD_USE_THIS
 264   ///
 265   /// \ingroup python_settings
 266   /// @brief \python_func{ setBool(id, value) }
 267   /// Sets the value of a setting.
 268   ///
 269   /// @param id                     string - id of the setting that the module needs to access.
 270   /// @param value                  bool - value of the setting.
 271   ///
 272   ///
 273   /// @note You can use the above as keywords for arguments.
 274   ///
 275   ///
 276   ///-----------------------------------------------------------------------
 277   /// @python_v20 New function added.
 278   ///
 279   /// **Example:**
 280   /// ~~~~~~~~~~~~~{.py}
 281   /// ..
 282   /// settings.setBool(id='enabled', value=True)
 283   /// ..
 284   /// ~~~~~~~~~~~~~
 285   ///
 286   setBool(...);
 287 #else
 288   void setBool(const char* id, bool value);
 289 #endif
 290
 291 #ifdef DOXYGEN_SHOULD_USE_THIS
 292   ///
 293   /// \ingroup python_settings
 294   /// @brief \python_func{ setInt(id, value) }
 295   /// Sets the value of a setting.
 296   ///
 297   /// @param id                     string - id of the setting that the module needs to access.
 298   /// @param value                  integer - value of the setting.
 299   ///
 300   ///
 301   /// @note You can use the above as keywords for arguments.
 302   ///
 303   ///
 304   ///-----------------------------------------------------------------------
 305   /// @python_v20 New function added.
 306   ///
 307   /// **Example:**
 308   /// ~~~~~~~~~~~~~{.py}
 309   /// ..
 310   /// settings.setInt(id='max', value=5)
 311   /// ..
 312   /// ~~~~~~~~~~~~~
 313   ///
 314   setInt(...);
 315 #else
 316   void setInt(const char* id, int value);
 317 #endif
 318
 319 #ifdef DOXYGEN_SHOULD_USE_THIS
 320   ///
 321   /// \ingroup python_settings
 322   /// @brief \python_func{ setNumber(id, value) }
 323   /// Sets the value of a setting.
 324   ///
 325   /// @param id                     string - id of the setting that the module needs to access.
 326   /// @param value                  float - value of the setting.
 327   ///
 328   ///
 329   /// @note You can use the above as keywords for arguments.
 330   ///
 331   ///
 332   ///-----------------------------------------------------------------------
 333   /// @python_v20 New function added.
 334   ///
 335   /// **Example:**
 336   /// ~~~~~~~~~~~~~{.py}
 337   /// ..
 338   /// settings.setNumber(id='max', value=5.5)
 339   /// ..
 340   /// ~~~~~~~~~~~~~
 341   ///
 342   setNumber(...);
 343 #else
 344   void setNumber(const char* id, double value);
 345 #endif
 346
 347 #ifdef DOXYGEN_SHOULD_USE_THIS
 348   ///
 349   /// \ingroup python_settings
 350   /// @brief \python_func{ setString(id, value) }
 351   /// Sets the value of a setting.
 352   ///
 353   /// @param id                     string - id of the setting that the module needs to access.
 354   /// @param value                  string or unicode - value of the setting.
 355   ///
 356   ///
 357   /// @note You can use the above as keywords for arguments.
 358   ///
 359   ///
 360   ///-----------------------------------------------------------------------
 361   /// @python_v20 New function added.
 362   ///
 363   /// **Example:**
 364   /// ~~~~~~~~~~~~~{.py}
 365   /// ..
 366   /// settings.setString(id='username', value='teamkodi')
 367   /// ..
 368   /// ~~~~~~~~~~~~~
 369   ///
 370   setString(...);
 371 #else
 372   void setString(const char* id, const String& value);
 373 #endif
 374
 375 #ifdef DOXYGEN_SHOULD_USE_THIS
 376   ///
 377   /// \ingroup python_settings
 378   /// @brief \python_func{ setBoolList(id, values) }
 379   /// Sets the boolean values of a list setting.
 380   ///
 381   /// @param id                     string - id of the setting that the module needs to access.
 382   /// @param values                 list of boolean - values of the setting.
 383   ///
 384   ///
 385   /// @note You can use the above as keywords for arguments.
 386   ///
 387   ///
 388   ///-----------------------------------------------------------------------
 389   /// @python_v20 New function added.
 390   ///
 391   /// **Example:**
 392   /// ~~~~~~~~~~~~~{.py}
 393   /// ..
 394   /// settings.setBoolList(id='enabled', values=[ True, False ])
 395   /// ..
 396   /// ~~~~~~~~~~~~~
 397   ///
 398   setBoolList(...);
 399 #else
 400   void setBoolList(const char* id, const std::vector<bool>& values);
 401 #endif
 402
 403 #ifdef DOXYGEN_SHOULD_USE_THIS
 404   ///
 405   /// \ingroup python_settings
 406   /// @brief \python_func{ setIntList(id, value) }
 407   /// Sets the integer values of a list setting.
 408   ///
 409   /// @param id                     string - id of the setting that the module needs to access.
 410   /// @param values                 list of int - values of the setting.
 411   ///
 412   ///
 413   /// @note You can use the above as keywords for arguments.
 414   ///
 415   ///
 416   ///-----------------------------------------------------------------------
 417   /// @python_v20 New function added.
 418   ///
 419   /// **Example:**
 420   /// ~~~~~~~~~~~~~{.py}
 421   /// ..
 422   /// settings.setIntList(id='max', values=[ 5, 23 ])
 423   /// ..
 424   /// ~~~~~~~~~~~~~
 425   ///
 426   setIntList(...);
 427 #else
 428   void setIntList(const char* id, const std::vector<int>& values);
 429 #endif
 430
 431 #ifdef DOXYGEN_SHOULD_USE_THIS
 432   ///
 433   /// \ingroup python_settings
 434   /// @brief \python_func{ setNumberList(id, value) }
 435   /// Sets the floating point values of a list setting.
 436   ///
 437   /// @param id                     string - id of the setting that the module needs to access.
 438   /// @param values                 list of float - values of the setting.
 439   ///
 440   ///
 441   /// @note You can use the above as keywords for arguments.
 442   ///
 443   ///
 444   ///-----------------------------------------------------------------------
 445   /// @python_v20 New function added.
 446   ///
 447   /// **Example:**
 448   /// ~~~~~~~~~~~~~{.py}
 449   /// ..
 450   /// settings.setNumberList(id='max', values=[ 5.5, 5.8 ])
 451   /// ..
 452   /// ~~~~~~~~~~~~~
 453   ///
 454   setNumberList(...);
 455 #else
 456   void setNumberList(const char* id, const std::vector<double>& values);
 457 #endif
 458
 459 #ifdef DOXYGEN_SHOULD_USE_THIS
 460   ///
 461   /// \ingroup python_settings
 462   /// @brief \python_func{ setStringList(id, value) }
 463   /// Sets the string values of a list setting.
 464   ///
 465   /// @param id                     string - id of the setting that the module needs to access.
 466   /// @param values                 list of string or unicode - values of the setting.
 467   ///
 468   ///
 469   /// @note You can use the above as keywords for arguments.
 470   ///
 471   ///
 472   ///-----------------------------------------------------------------------
 473   /// @python_v20 New function added.
 474   ///
 475   /// **Example:**
 476   /// ~~~~~~~~~~~~~{.py}
 477   /// ..
 478   /// settings.setStringList(id='username', values=[ 'team', 'kodi' ])
 479   /// ..
 480   /// ~~~~~~~~~~~~~
 481   ///
 482   setStringList(...);
 483 #else
 484   void setStringList(const char* id, const std::vector<String>& values);
 485 #endif
 486 };
 487 //@}
 488
 489 } // namespace xbmcaddon
 490 } // namespace XBMCAddon